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

package/docs/CORE_SERVICE.md

@@ -0,0 +1,97 @@
+# Core 服务与 harness 接入（0.3 alpha）
+
+0.3.0-alpha.1提供单根执行服务、连接授权/握手、正式 MCP stdio/Streamable HTTP、DSH 可选共享 Flow 连接与 [owner 持久选择 API](LOCAL_SELECTION.md)。**稳定 npm 0.2.7 不包含这些入口**；以下使用源码命令，安装alpha包后可将 `node bin/dsh-iris.js` 换为 `npx dsh-iris`。支持固定 `image-edit/v0`，显式新 v2 根另提供 [image-generate/v0 与 ComfyUI](IMAGE_GENERATION.md)，新 v3 根另提供 [speech/v0 与 transcribe/v0](AUDIO_FLOWS.md)，同时保留图片流程。[Web](LOCAL_WEB.md)按显式权限接入创作、观察、停止和选择，默认只读；服务器路径导出仍用 CLI，页面下载原字节。通用配置导出、用户能力/工具选择与功能覆盖见 [MCP 指南](MCP.md)。
+
+## 显式启动
+
+需要额外媒体协议时，可用重复的 `--provider-extension /absolute/entry.mjs` 在服务进程中显式加载可信扩展。注册实例随服务生命周期管理，启动本身不提交模型请求；harness 仍使用同一 Core 和原授权。见 [Provider 扩展](PROVIDER_EXTENSIONS.md)，不属于公开 npm 0.2.7。
+
+先准备新的专用根与已有的显式 Provider 配置，不迁移 DSH 或 v0 历史根：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/new-core
+node bin/dsh-iris.js execution init --data-root /absolute/new-core
+node bin/dsh-iris.js connection create --data-root /absolute/new-core \
+  --directory /absolute/new-mcp-pair --origin http://127.0.0.1:3182 \
+  --label my-client --scopes read,create,execute,stop --capabilities image-edit
+node bin/dsh-iris.js api serve --data-root /absolute/new-core \
+  --provider-config /absolute/providers.json --port 3182 \
+  --token-file /absolute/new-owner-token.txt --allow-execution \
+  --connections-file /absolute/new-mcp-pair/server-grants.json
+```
+
+`--allow-execution` 同时开启零生成上传/创建与有限执行；不传时保持既有默认只读行为。服务需要已初始化的 v1/v2/v3 执行根和有效的显式配置。配置静态校验、启动和连接握手不调用模型。每次明确继续至多调用一次 `flow.continue`：首次提交或检查/补交付原 Task，不持续轮询，不重提已有 Attempt。
+
+第二个执行 Host 无法取得同根 runner 租约；同根可另开只读页面。接收后服务自行收尾，关页或断开 harness 不撤销已接收操作。writer 正忙时明确拒绝新接收，调用方保留原 Key 后显式重试，不能假定已排队。
+
+也可使用 [连接中心](LOCAL_WEB.md#显式开启连接中心)在同一服务中提供页面、持久授权和 MCP。必须同时指定 `--allow-connection-management --connection-store`；需要执行时再显式添加 `--allow-execution --provider-config`，不会自动开启生成。默认 `web serve` 继续只读。连接管理目录单独持有租约，业务写入仍由这一个 Core runner 管理。
+
+媒体 API 的创建、执行和选择开关不依赖连接管理；`--allow-selection` 只允许 owner 在同 writer 中核对 Run 版本后保存选择，不启动 runner 或调用 Provider。执行开关不隐式开放选择，也不扩张 MCP 工具集。
+
+## 接收、查询与停止
+
+仍使用回环 HTTP、Bearer、Host/Origin 校验；连接端还需身份/实例头与已协商权限，详见 [连接契约](CORE_CONNECTIONS.md)。以下路由仅在显式执行模式开放：
+
+| 路由 | 输入 | 行为 |
+|---|---|---|
+| POST `/api/v0/runs/:id/continue` | `Idempotency-Key` UUIDv4，JSON `{expectedRevision}` | 完整 Operation 持久提交后返回 202；同 Key/输入返回 200 与原记录 |
+| GET `/api/v0/operations/:id` | 原 ID | 读取持久投影，不联系 Provider |
+| GET `/api/v0/operations?key=…` | 原 Key | 丢失响应后接回，不执行 |
+| GET `/api/v0/runs/:id/operations` | `limit` 1–30、`cursor` | 有界原操作列表 |
+| POST `/api/v0/operations/:id/cancel` | JSON `{}` | 先中止本地等待，待终态落盘后返回 200；重复原 ID 接回现有终态 |
+
+停止不另消费一个请求 Key，也不返回尚未持久化的取消 202。响应丢失时查询原 Operation。`localStopped` 只证明本地操作已停止，`remoteCancellation: not_requested` 表示没有请求远端取消；保留 Task 受理、结果和已交付作品。Operation succeeded 表示该次有限调用返回，作品是否完成仍看 Run/Task。
+
+queued/running 不因 GET 或 MCP 重连而执行。显式启动服务取得 runner 所有权和 writer 后，将遗留活动记录标记 interrupted，原 Key 仍接回它。用户确认后用新 Key、当前 Run revision 继续原流程；原 Task 有 Attempt 时只检查/交付原任务，受理未知不能自动再生成。
+
+正常退出先本地中止并落盘，再释放租约。强杀后分别检查 runner 与业务 writer；需要回显实际 stale PID 才能恢复：
+
+```bash
+node bin/dsh-iris.js execution inspect --data-root /absolute/new-core
+node bin/dsh-iris.js execution recover-lease --data-root /absolute/new-core --confirm-stale-pid 12345
+```
+
+若业务 writer 也遗留，先用 `doctor --data-root /absolute/new-core --json` 核对，再用 `runtime recover --data-root /absolute/new-core --confirm-stale-pid 实际PID` 显式恢复它；不自动清锁、删除记录或抢活跃进程。PID 活跃、未知或证据损坏均拒绝恢复。原子提交/强杀验证不等于断电、Windows ACL 或共享存储耐久保证。
+
+## 正式 MCP
+
+Core与桥分别管理生命周期：Core由用户明确启动，harness拥有stdio桥进程，HTTP网关复用同一Core。桥关闭先阻止新请求、取消本地网络等待并收尾初始化，不停止Core或撤销已受理Operation。SDK初始化、握手和关闭并发时保持终态；重复dispose共享结果，HTTP授权失效时释放原桥实例。检查命令与客户端预设见[MCP首次接入](MCP.md#首次接入与客户端预设)。
+
+本地服务启动失败或关闭时，会依次尝试释放HTTP、MCP、runner、应用与连接/Provider资源；某一步失败仍继续释放其余资源，再聚合报告具体阶段。snapshot的cleanupFailed表示释放失败，不能当成完全成功；不自动清锁或再次启动服务。
+
+Core 服务保持运行，在 harness 内配置下面的命令及参数：
+
+```bash
+node /absolute/iris/bin/dsh-iris.js mcp serve \
+  --connection-file /absolute/new-mcp-pair/client.json \
+  --scopes read,create,execute,stop
+```
+
+不指定 scopes 时只请求 `read`。这是随候选 npm 包分发的正式 stdio 入口：使用官方 `@modelcontextprotocol/server` SDK 处理协议与 schema，薄桥仅调用同一个已授权 Core 服务，不另起业务写者、不经 Bash 转调 CLI。stdout 只写 MCP 消息，连接凭据只在私有文件与 HTTP 头中出现。
+
+原 image-edit 工具契约为 `iris_core_connection/models/runs/run/import_image/create_run/continue/operation/lookup/stop/image/connections`，完整授权为 12 项，只读为 8 项。image-generate 另提供 `iris_core_create_generation`；只选文生图完整为 11 项，两组同时选择为 13 项，旧授权不扩张。参数是真实 Run、revision、请求 UUID、模型、Prompt、图片字节与作品 ID；不会替换成固定提示词。图片读取返回原 MIME/Base64 字节，不生成缩略图冒充原图。inline 导入 Base64 最多 8 MiB 字符，Core 图片读取上限仍为 64 MiB。
+
+MCP 调用取消或 EOF 只结束桥的本地请求；已经接收的 Operation 仍归 Core，重连按原 Key 查询。服务重启需显式 `iris_core_connection` 再握手；不会自动重试写调用。普通 EOF 断开连接，Core 离线时桥可关闭自身并记录远端断开未确认，不声称取消 Task。
+
+采用官方 SDK 2.3.1 / Core 2.3.1（Apache-2.0）和 Zod 4.6.7（MIT），Node 22 的 Linux ARM64 路径已有本机验证。stdio/HTTP 的 2025-11-25 与 2026-07-28 已分别验收，另以独立已安装 Client SDK 2.0.0/2.2.0 复核，不把它外推为全部品牌客户端或实际 Agent 使用均验收。[SDK 官方资料](https://github.com/modelcontextprotocol/typescript-sdk)。
+
+需要标准 HTTP MCP 时，在上面的 API 启动命令增加 `--allow-mcp`，使用 `origin/mcp` 和该连接的 Bearer 凭据；默认不开放。stdio/HTTP 共用能力/工具范围，HTTP 配置导出只写入新的私有文件，具体命令见 [通用 MCP](MCP.md)。
+
+## DSH 可选服务连接
+
+工作台可另显式增加 [供应商管理](PROVIDER_SETTINGS.md)与选择 [Panel](PANEL_EXTENSIONS.md)。这两者不扩大连接/MCP 权限：上游凭据留在 Core，普通 harness 不能读写供应商设置。
+
+使用同一个 `connection create`，将 harness 改为 `dsh`、输出改为新的独立目录。Core 的 `server-grants.json` 支持 1–32 个授权项；多连接时由操作者明确合并各 grants 数组，保留 UUID/secret 与 0600，随后显式启动服务读取它。连接配置不自动热重载。
+
+在你明确启动 DSH 时提供：
+
+```bash
+IRIS_CORE_CONNECTION_FILE=/absolute/dsh-pair/client.json \
+IRIS_CORE_SCOPES=read,create,execute,stop <your-existing-DSH-start-command>
+```
+
+首版为**新增共享 Flow 工具的可选连接模式**：原 17 项媒体工具、三项 DSH Skills 和原生 UI 保持；另注册与 MCP 相同的授权 `iris_core_*` 工具。图片通过真实 DSH attachment 服务交付。默认不设置此文件时，不连接服务、不新增工具。Core Skills 的 [显式安装器](CORE_SKILLS.md)继续独立，MCP 握手不替代 Skill 发现。
+
+此 DSH 原生共享桥仍限图片组；新 v3 语音/转写使用通用 MCP 或 Core Web。选择音频组会明确拒绝原生桥启动，避免注册尚无附件投影的工具；不影响原17项媒体工具的语音/转写。
+
+传统媒体工具继续使用原根；共享 Flow 仅使用连接所绑定的 Core 根。Core 离线时共享工具明确失败，不切回本地另生成。此模式尚未把整个旧媒体栈、浏览器/视觉/会话服务或 DSH UI 迁成远程 RPC。Core 连接中心现阶段创建通用 MCP 档案；DSH 原生服务授权仍由上述静态文件管理，不自动修改 DSH 设置。

package/docs/CORE_SKILLS.md

@@ -38,7 +38,7 @@ dsh-iris skills uninstall --target kimi
 
 ## 文件与装载
 
-`skills/iris-core/` 是独立目录，包含 `SKILL.md`、两份 `references/` 和可选的 `agents/openai.yaml` 界面元数据。参考链接均位于该目录内，分发时保留整个目录。
+`skills/iris-core/` 是独立目录，包含 `SKILL.md`、`references/` 和可选的 `agents/openai.yaml` 界面元数据。0.2.7配有CLI、任务两份参考；0.3.0-alpha.1增加独立ComfyUI参考。参考链接均位于该目录内，分发和安装时保留整个目录。
 
 使用支持 Agent Skills 的宿主时，将完整目录放到该宿主已确认的 Skill 搜索位置；已有同名目录先检查，不覆盖。仓库与 npm 包中的 `skills/` 也可作为显式搜索根。例如，在已安装 Kimi Code 的环境中独立验证：
 
@@ -50,13 +50,45 @@ kimi --skills-dir /absolute/path/to/iris/skills
 
 宿主读取 Skill 后仍需可执行的 `dsh-iris`，或已确认源码根中的 `node bin/dsh-iris.js`。向 Agent 提供本次明确的 Core 数据根；生成/编辑另提供私有 Provider 配置路径。先使用 `--help` 与只读配置摘要核对入口，具体命令见 [CLI 参考](../skills/iris-core/references/cli.md)。不要把密钥写进提示词或复制进 Skill。
 
+## ComfyUI 参考与 API 搭配（0.3 alpha）
+
+现有 `iris-core` 按需读取 [ComfyUI 参考](../skills/iris-core/references/comfyui.md)，说明工作流选择、公开参数、LoRA的模型/CLIP双权重和原任务恢复。正文仍为英文、标题附中文；本扩展从0.3.0-alpha.1提供，稳定0.2.7不包含。安装器随整个目录复制参考；已有安装须显式更新，不自动修改日常harness。
+
+ComfyUI 请求先集中确认尚缺少的图像目标、工作流、LoRA 与参数偏好；可以先只读查看真实目录辅助选择，关键要求明确后再创建和执行。沿用已有回答和授权，完整要求或明确委托选择时无需反复提问；普通 API 请求沿用所选 API 配置。工作流与参数 ID、类型、默认值及范围来自实际目录；服务当前可选 LoRA 等值须经明确的只读检查核实，不凭模型名称推断或自动安装节点。
+
+当前支持“ComfyUI 生成 → 同一 Core 根中的作品 → 支持改图的 API 精修”，第二步不携带 ComfyUI 参数，恢复第二步时保留第一步产物。反向“API 出图 → ComfyUI 图生图”的图片上传/绑定尚未接入。两种后端的独立对比会新增任务和可能的费用，按用户要求执行；不静默换后端，未知受理时保留原任务和请求身份。
+
 ## 当前边界
 
 - 首版覆盖图片及其任务，支持单步操作和图片续作；视频、语音和界面验收不在首版范围内。
-- DSH 原有三项 Skill、工具、附件与工作台流程保持，不把新 Skill 自动注册为第四项 DSH Skill；DSH 使用方式见 [README](../README.md#agent-skills)。
+- DSH 原有三项 Skill、工具、附件与工作台流程保持，不把新 Skill 自动注册为第四项 DSH Skill；DSH 使用方式见 [README](../README.md#dsh-插件027)。
 - 本版新增独立的 Core 指导，不迁移或改写旧 DSH Skill。后续若合并公共参考，应先证明 DSH 流程和资源解析保持。
 - Core Artifact ID 属于指定根，宿主附件、路径与 URL 不可互换；交付时由实际宿主呈现导出文件。
-- 正式 MCP 仍待实现。当前 Skill 的可执行说明只有 CLI，不能用它声称 MCP 已安装或第二生产 Host 已完成。
+- 0.3 alpha源码的正式 MCP 入口见 [Core 服务](CORE_SERVICE.md)，需独立配置授权连接。`iris-core` 的可执行说明仍是 CLI；下方连接专属 Skill 仅指导 MCP。Skill 安装不自动注册 MCP，不能据此声称日常 harness 已接入或真实 Agent 已验收。
 - 面向 Core 的独立工作台继续按既有路线推进；本 Skill 不描述尚不存在的 UI 操作。Skill 指导 Agent，业务受理、写者租约与重试约束继续由执行层负责。
 
 验收区分 Skill 文件/引用可读取、CLI 示例可执行、实际 Agent 是否按指导完成任务。离线供应商夹具只验证命令和状态处理，不证明真实模型的规划、生图质量或计费表现。
+
+## 连接专属 MCP Skill（0.3 alpha）
+
+面向 0.3 的源码[连接中心](LOCAL_WEB.md#显式开启连接中心)可按已保存连接生成说明。先保存功能/工具/操作权限，在“连接专属 Skill”中生成预览、下载 `iris-skill.json`，再用包含此功能的源码 CLI 安装：
+
+```bash
+node /absolute/iris/bin/dsh-iris.js skills install \
+  --bundle /absolute/downloads/iris-skill.json \
+  --directory /absolute/project/.agents/skills --dry-run
+node /absolute/iris/bin/dsh-iris.js skills install \
+  --bundle /absolute/downloads/iris-skill.json --directory /absolute/project/.agents/skills
+node /absolute/iris/bin/dsh-iris.js skills status \
+  --bundle /absolute/downloads/iris-skill.json --directory /absolute/project/.agents/skills
+```
+
+`--bundle` 同样支持 `uninstall` 和显式 `--target kimi`；该参数尚未进入 npm 0.2.7。下载的是最多 16 KiB 的普通 JSON 数据文件，由包内代码生成 `iris-mcp-<connectionId>/SKILL.md`，不安装外部传入 Markdown 或脚本。同名连接按 UUID 分开；原 `iris-core` 和 DSH 三项 Skill 保持。
+
+说明正文为英文、标题附中文，只包含当前有效工具；有限选择不暗示可以完成整套媒体流程。文件含连接/根身份与修订，不含 Token、Provider 密钥或私有路径，不能代替 MCP 配置，也不授予权限。只读服务导出只读工具；未开放的媒体组不生成假指令，零工具或已撤销连接不能生成说明。
+
+新 v3 根的 `tts`/`transcribe` 连接说明增加[音频指导](AUDIO_FLOWS.md)：按实际模型目录选择、音色不猜测、原音频作品导入与大小边界、明确继续/观察和原 Task 恢复，转写文本视为数据。标准 MCP audio 内容不保证每个客户端都有播放器；原 `iris-core` 的 CLI 图片说明与 DSH 三项 Skill 保持各自范围。
+
+文生图连接增加 ComfyUI 提问与参数指导：只有开放模型目录工具时才指导调用；未开放时说明缺口，要求可核实的当前目录或由 owner 调整授权，不越权改走 CLI。仅允许创建的连接明确不能执行；同时具备相应生成、改图、执行及查询工具时才加入 API/ComfyUI 串联说明。参数取自当前目录的 `comfyWorkflow.parameters`，创建时保存本次值；目录存在不等于服务或 GPU 已实测成功。
+
+授权改变后重新生成并显式安装；同包版本也比较内容，未经本地修改的旧副本会移到扫描根外备份后更新。本地改过的说明、未知目录或软链继续拒绝覆盖；卸载只归档。旧快照留在客户端时，Core 仍按实际授权拒绝已移除工具。安装器的 `discovery:not_checked` 仍要求在所用客户端另行确认发现与实际调用，浏览器只下载、不替用户选择安装路径。

package/docs/DSH_COMPATIBILITY.md

@@ -2,6 +2,16 @@
 
 Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安装的Iris版本；发布状态见 [README](../README.md)。
 
+## Iris 0.3.0-alpha.1
+
+本次alpha沿用下方12个准确宿主版本声明，独立Core Web/MCP不要求安装DSH。需要DSH新增的ComfyUI入口时明确安装预发布：
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.3.0-alpha.1
+```
+
+稳定通道仍为0.2.7。沿用声明不代表本次alpha重新实测了所有宿主组合；宿主/客户端SDK与实际装载结果仍须分别核对。
+
 ## Iris 0.2.7
 
 0.2.7 沿用 0.2.5/0.2.6 的以下 12 个准确版本声明。截图修复与实例装配不扩大宿主支持范围。连接引用另需供应商目录、脱敏设置及凭据公开服务；缺少接口时使用手动供应商。首次配置与升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。

package/docs/DSH_RC2_ADAPTATION.md

@@ -4,7 +4,7 @@
 
 本适配随 Iris `0.2.0` 发布；npm 0.1.4 包不包含这些后续修正。Iris 0.2.0 要求 Node.js `>=22.0.0`，DSH engines、五项客户端 peers 与 Host Doctor 仅放行准确版本 `0.2.0-rc.2`，不再沿用旧版支持窗口，也不推定其他 0.2 预览版或正式版兼容。
 
-旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 按历史验证范围使用稳定包 `@mokuyoaxis/dsh-iris@0.1.4`。安装与 npm tarball 下载方式见 [README](../README.md#最快开始)。保留的旧桥接与 fixture 测试不构成 Iris 0.2.0 的旧宿主支持承诺。
+旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 按历史验证范围使用稳定包 `@mokuyoaxis/dsh-iris@0.1.4`。安装与 npm tarball 下载方式见 [README](../README.md#快速开始)。保留的旧桥接与 fixture 测试不构成 Iris 0.2.0 的旧宿主支持承诺。
 
 Iris 0.2.1 沿用相同 Node/DSH 要求，新增 Artifact 改图工具后共注册 15 个工具；最新服务隔离检查为 31 项。宿主适配与业务功能分别验收，浏览器限制见下文。
 

package/docs/DSH_RUNTIME.md

@@ -1,5 +1,7 @@
 # DSH 实例运行时（0.2.7）
 
+0.3 alpha源码另可显式连接 [Core 服务](CORE_SERVICE.md)，添加共享 Flow 工具并复用原生附件；本文继续说明 0.2.7 的嵌入式媒体装配。可选连接不把整个旧媒体栈迁成远程调用，不改变下述历史数据根。
+
 面向 0.3 的内部装配已将 DSH 的 Core 写队列、Provider 连接解析引用和 Core 任务观察器归入插件实例。工具名、工作台路由、模型选择与计费规则保持；数据仍位于 `$DSH_HOME/iris/v1/core-v0`，不迁移既有 Task、Artifact、Run 或配置。
 
 ## 调用与归属
@@ -11,7 +13,7 @@ apply(ctx) → createDshRuntime({ dataRoot, getHost })
                   └─ Application Runtime → 操作级 Core → Command / Provider runner
 ```
 
-[DSH Host Adapter](../lib/dsh-host-adapter.js)继续把公开宿主服务映射为附件、浏览器、文本/视觉模型、连接和路由端口。[DSH 实例](../lib/dsh-core-adapter.js)负责这些端口与 Core 的组合，直接在进程内调用；不经本地 HTTP API，也没有模块级“当前实例”。`apply` 通过内部 `irisRuntime` 服务持有实例，注册的回调捕获各自所属实例。
+[DSH Host Adapter](../lib/dsh-host-adapter.js)继续把公开宿主服务映射为附件、浏览器、文本/视觉模型、连接和路由端口；工具调用时重新获取可能晚到的可选服务。[DSH 实例](../lib/dsh-core-adapter.js)负责这些端口与 Core 的组合，直接在进程内调用；不经本地 HTTP API，也不靠模块级“当前实例”路由业务命令。`apply` 通过内部 `irisRuntime` 服务持有实例，注册的回调捕获各自所属实例。路由部分注册失败时立即回滚已注册项。
 
 同一实例的 Core 写操作共用 [Application Runtime](CORE_RUNTIME_CONTRACT.md#应用运行时装配) 的 FIFO，每项独立取得和释放 writer。reader 独立运行，只读取已提交事实；多个读取不构成整个根的一致快照。不同根可并行，同一物理根的竞争写者返回 busy，空闲插件不一直占锁。
 
@@ -25,9 +27,11 @@ Core 自动观察仍由 DSH 实例提供有界定时节拍，每次至多执行
 
 排队取消不创建 Task；执行中取消保留已受理或未知的真实事实，不自动请求远端取消。附件展示失败或晚返回不会撤销已提交的 Core 成功结果。普通错误不阻塞后续队列；租约释放失败会停止实例，保留错误与现场，不报告关闭成功、不自动抢锁。
 
+legacy watcher 与 SSE 仍共享原有模块资源；原生装配只用“最近注册实例”标记阻止旧实例迟到释放时停止新资源，不以此宣称完整多 profile 隔离。可选 Core 服务桥启动失败会撤销已注册工具并断开握手；桥按当前所选插件业务注册工具，音频能力仍明确不支持。
+
 ## 当前边界与验证入口
 
-本轮实例化的是 DSH 的 Core 装配及上述操作。legacy `config.js`、`tasks.js`、`artifacts.js`、上传与 SSE 存储/资源仍保留原机制，不承诺同进程多个 profile 的完整隔离；其他 CLI 入口也未全部统一。固定 Flow 尚未接入 DSH 工作台，本地 API 的 Operation、执行/取消和真实 Web 联调另行推进。公开 SDK、包名、认证与数据格式均未因此改变。
+本轮实例化的是 DSH 的 Core 装配及上述操作。legacy `config.js`、`tasks.js`、`artifacts.js`、上传与 SSE 存储/资源仍保留原机制，不承诺同进程多个 profile 的完整隔离；其他 CLI 入口也未全部统一。固定 Flow 尚未接入 DSH 工作台；未发布的 Operation、执行/停止与真实独立 Web 见 [Core 工作台](LOCAL_WEB.md)。DSH 新增的 [ComfyUI 专区](IMAGE_GENERATION.md#dsh-工作台入口03-alpha)继续使用原 Task 装配，不要求迁移 Flow 根。公开 SDK、包名、认证与数据格式均未因此改变。
 
 - `npm test`：保留既有媒体与工作台断言，增加实例队列、关闭/租约失败及观察器竞态测试。
 - `node --expose-internals scripts/verify-dsh-host.mjs --dsh-root <绝对路径>`：隔离宿主服务验收包含异步卸载与重新装载；部分 SDK 需要额外指定 `--client-sdk-root`。

package/docs/HEADLESS_CLI.md

@@ -6,7 +6,7 @@
 
 需要Node.js ≥ 22.0.0。按 [README](../README.md) 核对发布状态，安装 `npm install @mokuyoaxis/dsh-iris@0.2.7` 后运行 `npx dsh-iris --help`。源码入口为 `node bin/dsh-iris.js ...`；本地tarball也可用于安装。
 
-0.2.7 另提供宿主无关的 [`iris-core` Skill](CORE_SKILLS.md)，指导 Agent 使用这些图片、任务和作品命令；英文正文附中文标题，独立分发，不改变 DSH 三项 Skill。`skills install/status/uninstall` 可显式复制、检查和可恢复卸载，支持 Kimi 或自定义扫描目录，安装/卸载可 `--dry-run`。这些入口随 npm 0.2.7 分发；正式 MCP 仍待实现。
+0.2.7 另提供宿主无关的 [`iris-core` Skill](CORE_SKILLS.md)，指导 Agent 使用这些图片、任务和作品命令；英文正文附中文标题，独立分发，不改变 DSH 三项 Skill。`skills install/status/uninstall` 可显式复制、检查和可恢复卸载，支持 Kimi 或自定义扫描目录，安装/卸载可 `--dry-run`。这些入口随 npm 0.2.7 分发；该发行版不含正式 MCP，当前alpha源码的 Web/MCP 另见 [Core 快速开始](CORE_QUICKSTART.md)。
 
 0.2.1 提供 `vision look / locate / ocr / summarize`。文件输入的纯视觉不需要数据根，支持显式模型覆盖、JSON/文本、结果和拼图文件；图片/帧 Artifact ID 输入需显式数据根，以 reader 读取既有 Core 产物，只有主动音轨转写才创建 Core Task/Artifact。完整命令与输出规则见 [独立视觉 CLI](VISION_CLI.md)；S2V、HTML、配置、等待及批量管理见 [CLI 管理](CLI_MANAGEMENT.md)。
 
@@ -32,7 +32,7 @@ dsh-iris doctor --data-root /absolute/path/to/iris-data --json
 
 ## 异常退出后的写者租约
 
-SIGINT/SIGTERM 可被 CLI 捕获并释放运行中的租约；SIGKILL、OOM 或断电可能留下租约。后续写操作返回 `IRIS_CORE_DATA_ROOT_BUSY` 时，先用 `doctor --data-root <absolute-path> --json` 只读查看 `core-writer-lease`。仅当报告中的 owner PID 为 `missing`，并且你已确认没有跨主机或其他仍在写入的进程，才可显式回显该 PID：
+POSIX 上的 SIGINT/SIGTERM 可被 CLI 捕获并释放运行中的租约；Windows 请使用运行终端的 Ctrl+C 正常关闭。Windows 上 Node 的 `child.kill('SIGTERM')` 会强制结束进程，不能据此期待清理回调执行，见 [Node 信号说明](https://nodejs.org/docs/latest-v22.x/api/process.html#signal-events)。SIGKILL、OOM 或断电也可能留下租约。后续写操作返回 `IRIS_CORE_DATA_ROOT_BUSY` 时，先用 `doctor --data-root <absolute-path> --json` 只读查看 `core-writer-lease`。仅当报告中的 owner PID 为 `missing`，并且你已确认没有跨主机或其他仍在写入的进程，才可显式回显该 PID：
 
 ```bash
 dsh-iris runtime recover --data-root /absolute/path/to/iris-data --confirm-stale-pid 12345

package/docs/IMAGE_FLOW.md

@@ -1,5 +1,9 @@
 # 固定图片流程（0.2.7）
 
+0.3 alpha源码另提供 [image-generate/v0 与 ComfyUI 入口](IMAGE_GENERATION.md)，需显式的新 v2 执行根；下文保留 0.2.7 的原固定编辑流程，旧根不自动迁移。
+
+0.3 alpha源码可通过 [Core 执行服务](CORE_SERVICE.md)、正式 MCP 和 DSH 可选共享 Flow 连接消费同一固定流程，另有显式启用的 [owner 持久选择 API](LOCAL_SELECTION.md)。真实 [Core 工作台](LOCAL_WEB.md)已接入创作、执行与选择；本文保留已发布 0.2.7 的 CLI 使用方式。
+
 0.2.7 提供 `image-edit/v0`：导入原图 → 指定模型改图 → 本地像素比较 → 选择原图或新版 → 导出。真实执行入口是独立 CLI 和内部应用运行时，尚未接入 DSH 工作台或真实独立 Web；[Web Demo](WEB_PROTOTYPE.md)仅说明面向 0.3.0 的交互方向。本流程从 npm 0.2.7 起随包分发。
 
 0.2.7 另提供 [默认只读 API](LOCAL_API.md)查看已有流程与图片；新空专用根可主动启用 [本地上传与创建](LOCAL_CREATION.md)。这些 HTTP 入口不执行/继续流程，也不把 CLI 的导出路径暴露给浏览器。

package/docs/IMAGE_GENERATION.md

@@ -0,0 +1,127 @@
+# Core 文生图与 ComfyUI（0.3 alpha）
+
+当前源码支持固定 `image-generate/v0`：无需原图，使用明确的 `provider::model` 和提示词生成一张图片。它与改图共用 Run、Operation、Task、作品、原 Key 恢复和有限执行；生成结果无需像素比较，明确选择后可下载或用作下一次改图的原图。**npm 0.2.7 不包含本页的新流程、页面或 MCP 入口。**
+
+## 新建支持文生图的工作区
+
+在新的专用位置初始化 v2 执行根；不要转换现有数据根：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/new-image-core
+node bin/dsh-iris.js execution init --data-root /absolute/new-image-core --image-generation
+node bin/dsh-iris.js web serve --data-root /absolute/new-image-core \
+  --provider-config /absolute/private-providers.json \
+  --token-file /absolute/new-owner-token \
+  --allow-execution --allow-selection --allow-provider-management
+```
+
+v2 可同时保存文生图和改图。原 v0/v1 根继续支持原编辑行为，不自动升级、迁移或开启新功能；旧写者拒绝 v2。连接凭据与恢复身份仍绑定各自的 rootId。
+
+在创作设置选择“生成图片”，明确选择模型、填写画面描述，再点击“开始生成”。创建和执行各使用独立 Key，双击合并；创建结果未知时先找回原 Run，不自动开始生成。修改已有输入需新建流程。
+
+CLI 也可创建同一流程，创建本身不调用模型：
+
+```bash
+node bin/dsh-iris.js flow create --data-root /absolute/new-image-core \
+  --provider-config /absolute/private-providers.json \
+  --input '{"model_ref":"my-provider::my-model","prompt":"A violet iris in soft morning light","n":1}'
+node bin/dsh-iris.js flow continue run_REPLACE_WITH_RETURNED_ID \
+  --data-root /absolute/new-image-core --provider-config /absolute/private-providers.json
+```
+
+`run_REPLACE_WITH_RETURNED_ID` 须替换为创建实际返回的 Run ID。后续继续、选择和导出见 [图片流程](IMAGE_FLOW.md)。已有 Task 有 Attempt 时只处理原任务；受理未知不重新提交。异步任务每次“查看原任务”只观察一次；“停止等待”不等于远端取消或停止计费。
+
+## ComfyUI 入口
+
+需要你已运行的 ComfyUI HTTP 服务和一份能在该服务上执行的 API 工作流。Iris 不安装 ComfyUI、模型或自定义节点，不启动 GPU 服务；独立网页不嵌入节点编辑器。
+
+1. 供应商页选择“ComfyUI · 已有服务”，填写 Iris Core 能访问的地址；本机通常是 `http://127.0.0.1:8188`。远程 Core 的这个地址指向 Core 所在机器。原生 ComfyUI 可选无需认证，受保护的反向代理可使用 API Key/Bearer；不提供 Comfy Cloud/OAuth 登录适配。
+2. 在 ComfyUI 使用 **Export (API)** 导出。展开“ComfyUI 工作流”，导入 API 图或完整 Iris v0/v1 模板，最多 40 KiB、256 个节点；参数声明也计入模板大小。普通画布格式不能直接执行。
+3. 填写稳定的工作流名称，明确正向提示词节点（替换其 `inputs.text`）、图片输出节点和可选尺寸节点（替换 `inputs.width/height`）。展开“开放参数”，勾选已有标量输入、命名并选择整数/小数类型；右侧设置区提供使用时的表单预览。完整 v1 模板保留原参数 ID、类型、范围、选项和顺序。
+4. 已保存、启用的 ComfyUI 连接可做“只读检查”，不保存草稿、不创建 Task、不入队。点击“加入模型草稿”，同名替换需确认，再“保存设置”。连接地址或密钥尚有编辑时，先保存连接，再重新导入模板检查。
+5. 创作页选择此工作流，填写提示词及开放参数。LoRA 槽位分别显示模型与 CLIP 权重，更多参数默认折叠；“检查参数并读取选项”取得当前服务的候选，超出 256 项时保留手填。检查不会替换当前参数；修改输入或切换工作流使旧检查结论失效。
+6. “开始生成”才提交一次工作流，之后明确查看原任务并取回图片。没有绑定尺寸节点时使用模板尺寸，页面禁用尺寸覆盖。首次 v1 提交前后端重新检查实际参数；服务缺少节点/模型或执行失败时，请结合原 ComfyUI 任务检查。
+
+“打开 ComfyUI”在浏览器新标签打开所填服务地址；它不为远程服务建立代理或转发。工作流可调用节点自己的外部服务，应只导入你了解的流程。原始图配置保存在私有 Provider 文件及其备份中，普通设置读取只显示摘要和绑定，不回显图正文；不要将账号凭据写入图节点。
+
+参数表单按模板声明显示，不添加 LoRA 节点或安装模型；多个 LoRA 需要原图已有多个槽位。只读检查需 owner 与 `--allow-provider-management`，仅执行连接仍可填写已开放的参数并按原权限生成。生成点击时固定本次参数快照，新 v1 表单保存全部开放参数的取值；草稿不写入 sessionStorage，恢复表仍只保存请求身份。结果的“流程详情”显示 Run 中实际记录的参数 ID 与值，不用最新模板默认值补写历史；未记录的输入仍依赖原模板。真实 GPU 出图、节点级进度和推理预览尚未验收或接入。
+
+运行时使用 `/prompt`、`/history/{prompt_id}`、`/queue` 和 `/view`。历史和队列都找不到的原任务标记未知，不重新排队。取图只接受原服务的图片接口，不读取 ComfyUI 机器上的任意文件路径。工作流摘要进入原 Task 连接绑定；更改工作流后旧任务不会悄悄改用新图恢复。首版不调用共享服务的全局 `/interrupt`。
+
+协议依据：[官方路由](https://docs.comfy.org/development/comfyui-server/comms_routes)、[API 工作流示例](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/basic_api_example.py)、[原任务与取图示例](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example.py)。Iris 仅接入 HTTP 协议，不随包分发 ComfyUI 或其运行依赖。
+
+2026-10-26 已在线复核官网及官方源码提交 [`fe298e4`](https://github.com/Comfy-Org/ComfyUI/tree/fe298e4e20f1ff26d30e8639267bbd0b57811390)。以下是当前适配边界，源码核对与受控测试不代替真实 GPU 验收：
+
+- [`POST /prompt`](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/server.py#L1164) 会验证并入队，不是只读验证接口。Iris 的只读检查只 GET 节点定义；实际生成才提交一次，并以返回的任务 ID 查询历史/队列，取图沿用官方的文件名、子目录和类型参数。
+- [LoRA 官方定义](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/nodes.py#L714)分别提供模型与 CLIP 权重，多个 LoRA 依靠已有节点串联。候选来自服务端节点定义；Iris 不直接扫描模型目录。
+- 官方当前支持[带任务 ID 的中断](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/server.py#L1262)，但 Iris 首版尚未接入，仍不发送远端 `/interrupt`；停止等待不表示远端已取消。
+- 官方[采样器种子](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/nodes.py#L1606)支持 unsigned 64-bit；Iris 的整数输入限于 JavaScript 安全范围。API 图中直接填写的越界整数也会拒绝，请将种子调至 `0`–`9007199254740991` 后重新导出，避免静默舍入。
+- Iris 提交整份图，只导入所选输出节点的一张图片；其他输出节点或图内外部服务仍可能执行。[SaveImage](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/nodes.py#L1669)默认可把图与提示词写入 PNG 元数据，Iris 保留原字节，不自动移除这些元数据。
+
+## DSH 工作台入口（0.3 alpha）
+
+当前源码另在原 DSH 工作台中提供专用区域；**npm 0.2.7 尚不包含以下 ComfyUI 界面**。它使用 DSH 侧原配置和 Core Task，不要求另起独立 Core 服务或创建 v2 Flow 根，也不自动接管独立 Core 面板的配置。
+
+1. “设置 → Iris 工作台 → + 添加供应商”，选择“ComfyUI · 已有服务”。默认地址为 `http://127.0.0.1:8188`，按 DSH 进程可访问的地址修改；可选无需认证或 Bearer。保存连接不探测服务、不生成图片。
+2. 在该供应商中导入原始 **Export (API)** 图或完整 Iris v0/v1 模板。明确正向提示词、图片输出和可选尺寸节点；展开“公开参数”，勾选已有标量输入。LoRA 名称、模型权重、CLIP 权重可以分别公开；节点连接不可勾选。普通画布 JSON 不支持。
+3. “只读检查”仅查询已保存服务的节点定义，不保存草稿、不创建 Task、不入队。修正问题后点击“保存工作流”；同名替换另行确认，原摘要不符时拒绝覆盖。保留原 JSON，后续修改模板需再次导入。
+4. 可明确勾选“保存时将图片功能设为自动池”；首次空配置默认勾选，已有功能池保持原选择。未启用时，到“功能池与调用方式”纳入此工作流。
+5. 展开“创作工具 → 画图”，选择具体工作流，再展开默认收起的“工作流参数”。“只读检查并读取选项”可取得服务当前公布的 LoRA、采样器等候选；超出 256 项时可手填名称。多个 LoRA 依赖原图已有节点，不会自动插入或安装模型。
+6. 点击“生成图片”才创建生成 Task。请求前重新核对模板摘要；v1 模板还检查实际参数的节点定义。参数改变会清除旧检查结论，切换模型会清空本卡片的参数覆盖。提交结果未知时先查任务列表，不自动重试或改用另一模型。
+
+地址与认证收在默认折叠的“连接设置”，外观跟随 DSH；进入 ComfyUI 区域有一次短暂鸢尾扫光，遵循减少动画设置。工作台和泡泡常用卡片复用同一画图控件。能力健康中的 ComfyUI 实测转到画图表单，实际生成保留受理/观察/作品事实；静态检查通过不表示真实 GPU 出图通过。
+
+## ComfyUI 参数模板与只读检查（后端）
+
+当前后端支持 `comfyWorkflow.version: 1`，在已有 `graph`、`promptNode`、`outputNode` 和可选 `sizeNode` 上增加明确的 `parameters`。原 v0 模板保持；Core 与 DSH 工作台均支持导入、声明及填写参数。没有开放参数时仍保存 v0 固定模板；v1 完整模板也可通过 CLI `providers add/set` 的 `models[].comfyWorkflow` 保存。
+
+例如，已有图中的 `10` 是 LoRA 节点、`7` 是负面提示词节点、`3` 是采样器，可声明下列参数。此片段只是参数声明，须与原 API 图和输入输出绑定一起保存：
+
+```json
+{
+  "parameters": [
+    {"id":"lora","label":"LoRA","node":"10","input":"lora_name","type":"string"},
+    {"id":"model_weight","node":"10","input":"strength_model","type":"number","min":-2,"max":2},
+    {"id":"clip_weight","node":"10","input":"strength_clip","type":"number","min":-2,"max":2},
+    {"id":"negative","node":"7","input":"text","type":"string"},
+    {"id":"seed","node":"3","input":"seed","type":"integer","min":0},
+    {"id":"steps","node":"3","input":"steps","type":"integer","min":1,"max":100}
+  ]
+}
+```
+
+最多开放 32 个已有标量输入，类型为 `string`、`integer`、`number`、`boolean`，可加数值 `min/max` 或有限 `choices`；默认值来自图，且必须符合声明。参数 ID 和目标不能重复，不能覆盖已绑定的正向提示词或尺寸，也不能替换节点连接。LoRA 模型权重和 CLIP 权重分别声明；多个 LoRA 可使用图中不同节点的不同槽位。整数限制在 JavaScript 安全整数范围，不支持完整 unsigned 64-bit seed。
+
+先做一次只读检查，可提供准备使用的参数：
+
+```bash
+node bin/dsh-iris.js models workflow-check comfy::portrait \
+  --provider-config /absolute/private-providers.json \
+  --input '{"workflow_parameters":{"lora":"portrait.safetensors","model_weight":0.7,"clip_weight":0.4,"seed":42}}'
+```
+
+检查只 GET 官方 `/object_info/{node_class}`，每类查询一次，整体默认限时 15 秒。它报告缺失节点、必需输入、可判断的连接引用/类型、标量范围和枚举，包括节点公布的 checkpoint/LoRA 文件名。结果的 `ok` 仅表示这些静态条件满足；不执行节点、自定义校验或推理，不验证模型家族、显存与外部服务，不证明真实出图成功。参数的 `value` 是本次检查值；模型目录中的 `default` 仍是原模板默认值。候选参数选项最多返回 256 个，超出会标记截断；不扫描磁盘或安装模型。`ok:false` 的业务检查结果仍作为 JSON 正常返回，应读取 `ok/issues`。
+
+v1 模板在每次首次提交前重新检查实际参数与尺寸，检查失败或检查网络中断属于未受理，不发送 `/prompt`；真正 POST 入队后的响应丢失仍保守记为受理未知。v0 固定模板沿用原提交行为，可主动运行上述只读检查。
+
+用 CLI 创建带参数的持久流程：
+
+```bash
+node bin/dsh-iris.js flow create --data-root /absolute/new-image-core \
+  --provider-config /absolute/private-providers.json \
+  --input '{"model_ref":"comfy::portrait","prompt":"An iris portrait","n":1,"workflow_parameters":{"lora":"portrait.safetensors","model_weight":0.7,"clip_weight":0.4,"negative":"","seed":42}}'
+```
+
+HTTP `POST /api/v0/generations` 和 MCP `iris_core_create_generation` 使用可选 `workflowParameters` 对象；`iris_core_models` 返回已明确开放的参数描述。配置检查需 owner 与 `--allow-provider-management`，通过 `POST /api/v0/provider-management/workflow-check` 发送 `{expectedRevision,modelRef,workflowParameters?}`。未保存的模板可改用 `{expectedRevision,providerId,comfyWorkflow,workflowParameters?}`，仅访问已保存且启用的 ComfyUI 连接，不接受临时地址或凭据；两种选择不能混用。检查不写配置或创建 Task，配置在检查期间变化会拒绝旧结果。普通目录读取仍只列已配置工作流。
+
+单次参数最多 24 KiB，参数化 CLI 输入最多 96 KiB；HTTP 正文仍最多 64 KiB。参数会排序并纳入创建 Key 和 Run 输入摘要；同 Key 不同值冲突，同值不同键顺序可重放。带参数 Run 使用记录版本 2，旧读取者拒绝；无参数 Run、原固定模板和摘要保持，已有根不迁移。这里保存的是请求参数和模板绑定摘要，不保存另一份完整图；原模板改变后仍按原规则拒绝将旧任务重新绑定到新模板，并清除该图片模型的过期实测标记。原 Task 的远端查询不重新检查节点目录或生成。
+
+## MCP 能力选择
+
+连接中心的图片组分别选择“生成图片”和“修改图片”；CLI 对应 `image-generate`、`image-edit`，可逗号组合。文生图新增 `iris_core_create_generation`，参数为原请求 UUID、明确模型、提示词、可选尺寸及明确开放的 ComfyUI `workflowParameters`；创建后通过共享的 `iris_core_continue` 明确执行。
+
+只选择文生图时不注册导入/改图创建工具。原连接默认仍为 image-edit 和原 12 工具，不自动增加能力；两个功能都选且具备全部操作权限时共 13 工具。继续、Run/Operation 和已绑定作品读取都核对流程所属能力；这不是同一用户不同连接之间的租户隔离。配置与传输见 [通用 MCP](MCP.md)。
+
+## 验证范围
+
+定向验证覆盖根版本、稳定步骤/Task、重复 Key、未知受理不重提、原结果恢复、选择/下载、MCP stdio/HTTP 授权和真实 Chromium 操作。ComfyUI HTTP 服务响应为受控夹具，未进行真实 GPU/节点/模型出图验收；没有调用付费媒体。实际服务、反向代理与自定义节点仍需在你的部署上验证。

package/docs/LOCAL_API.md

@@ -1,8 +1,10 @@
 # 只读本地 API（0.2.7 / I4A）
 
-0.2.7 增加显式启动的本地 HTTP 入口，默认只提供 GET/HEAD，用来验证无 DSH 环境下的流程查询与图片访问。另有主动启用的 [本地上传与创建](LOCAL_CREATION.md)；继续、选择和取消等执行接口尚未开放。安装包不会自动启动本服务。
+0.3 alpha源码另有 [Core 有限执行与 harness 服务](CORE_SERVICE.md)和 [owner 持久选择](LOCAL_SELECTION.md)，需独立显式开启。本文其余内容说明已发布 0.2.7 的默认只读与零生成创建范围；执行实现及连接协议以上述指南为准。[真实 Web](LOCAL_WEB.md)已按权限接入固定图片创作、选择及连接管理，默认仍只读。
 
-现有 [Web Demo](WEB_PROTOTYPE.md)继续保留为面向 0.3.0 的交互说明，尚未连接这个 API；界面和交互细节到 0.3.0 阶段统一润色。[完整 API 契约](LOCAL_API_CONTRACT.md)中的执行与 Operation 部分仍是设计稿。
+0.2.7 增加显式启动的本地 HTTP 入口，默认只提供 GET/HEAD，用来验证无 DSH 环境下的流程查询与图片访问。另有主动启用的 [本地上传与创建](LOCAL_CREATION.md)；0.2.7 不含继续、选择和取消接口，开发源码的对应入口见上方指南。安装包不会自动启动本服务。
+
+现有 [Web Demo](WEB_PROTOTYPE.md)继续保留为面向 0.3.0 的交互说明，尚未连接这个 API；界面和交互细节到 0.3.0 阶段统一润色。[完整 API 契约](LOCAL_API_CONTRACT.md)分别说明已发布能力和未发布的执行、选择实现。
 
 ## 显式启动与停止
 

package/docs/LOCAL_API_CONTRACT.md

@@ -1,12 +1,20 @@
 # 独立本地 API 契约（0.3 / I4）
 
-0.2.7 已实现 **I4A 默认只读**与 **I4B 显式本地创建**：显式本机监听、Bearer/Host/Origin、受控流程/媒体，以及主动启用的上传/创建与持久身份接回，见 [只读 API](LOCAL_API.md)和 [本地创建](LOCAL_CREATION.md)。**继续/选择、Operation 与执行取消仍是设计稿**；本契约尚未冻结为公开 SDK，上述 I4A/I4B 入口随 npm 0.2.7 分发。
+0.2.7实现 **I4A 默认只读**与 **I4B 显式本地创建**：显式本机监听、Bearer/Host/Origin、受控流程/媒体，以及主动启用的上传/创建与持久身份接回，见 [只读 API](LOCAL_API.md)和 [本地创建](LOCAL_CREATION.md)。0.3.0-alpha.1另提供 [有限执行服务](CORE_SERVICE.md)、[连接握手](CORE_CONNECTIONS.md)与 [owner持久选择](LOCAL_SELECTION.md)。本契约尚未冻结为公开SDK；稳定0.2.7只包含上述I4A/I4B入口。
 
-当前固定流程的真实执行入口仍是 [CLI](IMAGE_FLOW.md)；[独立 Web Demo](WEB_PROTOTYPE.md)只消费内存演示，保留到 0.3.0 阶段统一润色。它尚未接入只读 API，也不作为完整服务或写操作已经实现的依据。
+已发布固定流程通过 [CLI](IMAGE_FLOW.md)执行，0.3 alpha源码另有上方 Core 服务；[独立 Web Demo](WEB_PROTOTYPE.md)只消费内存演示，保留到 0.3.0 阶段统一润色。Demo 尚未接入只读 API，也不作为完整服务或写操作已实现的依据。
+
+0.3 alpha源码另有 [Core 工作台](LOCAL_WEB.md)，通过显式 `web serve` 同源提供固定静态资源；登录页不包含私有数据，API/图片仍要求 Bearer。默认只读，创建、执行和选择分别显式开启，不要求连接管理；页面按能力接入改图、比较、选择、停止和下载。npm 0.2.7 尚不含，不改变下方已发布 I4A/I4B 的能力边界。
+
+源码另实现 [Operation 存储与版本门禁](LOCAL_OPERATIONS.md)，只在新专用根主动初始化；显式 `api serve --allow-execution` 装配 runner、持久接收/查询与本地停止，默认模式与刷新恢复仍只读。v1 根复用零生成创建，写者拒绝损坏记录；具体执行与握手以服务指南为准。
+
+0.3 alpha源码的 [Core 音频流程](AUDIO_FLOWS.md)另在新 v3 根增加 `/audio-models`、`/audio`、`/speeches`、`/transcriptions`、作品 `/audio` 和 `/text`，以及 Run 类别筛选。音频与图片共用原 runner/Task/Key；现有图片 `/content` 保持图片类型限制。播放/下载最多64 MiB音频或1 MiB文本，输入音频最多20 MiB且核对容器/MIME，不接收任意路径/URL。下方 I4A/I4B 表继续描述已发布图片切片，不能据此把音频入口用于旧根。
+
+源码另有 owner 专用只读 `GET/HEAD /api/v0/capabilities`：返回 `contractVersion:0,state,scopeOptions,controlTools,groups,tools,media,plugins,contributions`，装配插件时附 Core 版本及准确贡献依赖。无模型密钥、数据根或可加载脚本路径；无凭据401，连接凭据403，未知查询参数400。此完整目录不表示当前用户授权或媒体健康。连接管理目录复用同一投影并另附 availableScopes/defaults 等服务选项；`session.operations` 由 Core 的 Web 映射和实际根版本、开关、授权交集生成。详情见 [插件目录](PLUGINS.md#core-能力目录与授权)，不改变已发布 I4A/I4B 的契约范围。
 
 ## 1. 实例与启动
 
-一个服务实例显式绑定一个已初始化的专用 Flow 根和一个 Application Runtime。Provider 配置来源可显式提供，省略时仍可查看已有流程/图片，启用本地写入后也可上传；模型列表返回未配置，不能创建新 Run。由用户主动启动，固定仅监听 `127.0.0.1`；首次不支持远程监听、代理转发或自动扫描 DSH 配置。CLI 的 `flow init` 仍负责初始化新根，浏览器不能指定根路径、初始化旧根或变更 Provider 配置。
+一个服务实例显式绑定一个已初始化的专用 Flow 根和一个 Application Runtime。Provider 配置来源可显式提供，省略时仍可查看已有流程/图片，启用本地写入后也可上传；模型列表返回未配置，不能创建新 Run。由用户主动启动，固定仅监听 `127.0.0.1`；首次不支持远程监听、代理转发或自动扫描 DSH 配置。CLI 的 `flow init` 仍负责初始化新根，浏览器不能指定根路径或初始化旧根。未发布 C3 另以独立开关提供 owner 供应商管理，只操作启动时固定的配置，见 [管理契约](PROVIDER_SETTINGS.md)。
 
 API 使用 `/api/v0` 前缀，后续静态页面须与 API 同源。只有 HTTP 适配器负责验证外部输入、生成受控 DTO 和管理请求；不得把 `application.execute(name, input)`、现有 DSH `serveApi` 或 CLI 参数作为通用 HTTP 转发口。模型来自显式配置中允许改图的候选，Flow 继续绑定单一明确模型与 `n=1`。
 
@@ -14,9 +22,12 @@ I4B 的上传与 Run 创建均不生成，完成本地提交后返回 201，同
 
 ## 2. 身份与浏览器边界
 
-- 每次启动产生 32 字节随机会话 Token，CLI 通过必填 `--token-file` 写入新的根外私有文件（POSIX 0600），不打印 Token。服务鉴权使用 Token 摘要和等时比较；调用进程读取私有文件，以 `Authorization: Bearer …` 发送，不进入 URL、命令行参数、Run、日志或错误文本。未来浏览器只在标签页内存保留 Token；页面重新连接不开始生成。首版文件交付替代最初的终端显示提案，支持自动化且避免管道日志收集 Token。
-- **所有 API，包括模型列表、状态与媒体，都验证身份**；Token 比较使用等时比较。首版不使用 Cookie，也不建立“同源就已认证”的假设。退出页面丢弃客户端 Token；停机使该进程 Token 失效。
+- `api serve` 每次启动产生32字节随机 owner Token，CLI 通过 `--token-file` 或 `--token-dir` 写入新的根外私有文件（POSIX0600），不打印 Token。服务鉴权使用摘要和等时比较；调用进程读取私有文件，以 `Authorization: Bearer …` 发送，不进入 URL、命令行参数、Run、日志或错误文本。普通 `web serve` 改由根外私有认证存储管理口令与浏览器会话；记住设备时浏览器独立凭据保存在 origin 隔离的 localStorage，普通模式用 sessionStorage，不保存口令或 owner/MCP 密钥。刷新先 GET 验证，不开始生成，见[工作台登录](WORKBENCH_LOGIN.md)。
+- 模型列表、业务状态、媒体与管理 API 均要求 Bearer 身份；owner Token 使用摘要及等时比较。不使用 Cookie，也不建立“同源就已认证”的假设。工作台主动退出经服务确认后撤销当前浏览器会话，401清除失效的客户端登录；口令模式的有效浏览器会话跨正常重启保留，进程 owner 控制令牌仍轮换。
+- 普通 `web serve` 的有限登录入口为 `GET/HEAD /api/v0/workbench/auth`、严格同源 `POST /setup`、`POST /password-login`、`POST /logout`（后三者均在 `/api/v0/workbench` 下），字段和权限见[口令接口](WORKBENCH_LOGIN.md#接口与装配)。首次设置要求启动器交付的随机片段票据，没有10分钟窗口，成功后失效。`POST /setup-link` 与 `/password-reset` 只接受本机 owner 控制令牌，浏览器及 MCP 凭据不可调用。
+- 显式 `--token-file` / `--token-dir` 的旧工作台模式保留 `POST /api/v0/workbench/login`、`/login-link` 和10分钟一次性链接；票据与浏览器身份仅在进程内保留摘要，服务重启失效。口令模式拒绝这两个旧接口。`api serve` 不开放工作台登录入口，MCP仍使用连接专属凭据。
 - `Host` 必须精确匹配实际监听 authority。带 `Origin` 的请求仅允许该页面精确 origin；`Origin: null`、外站 origin 和不匹配 Host 拒绝，不采信 `Forwarded` 或 `X-Forwarded-*`。无 Origin 的本机 CLI 请求仍须通过 Host 与 Token 检查。不同 origin 的 OPTIONS 不开放 CORS。
+- 公开工作台首页允许外站顶层GET导航，以便直接点击登录链接；必须是document/navigate，不把此例外用于iframe、脚本、外站fetch或业务API，Host和已有Origin检查仍保留。
 - 当前 API 响应使用限制性 CSP。未来页面的脚本/样式只从本站加载，无内联脚本、第三方资源、对象、框架嵌入或表单提交；用户内容用文本节点展示，媒体通过带认证的 fetch 获取 Blob 后展示/下载，不将 Token 放入 `<img>` URL。
 - JSON、状态、媒体和错误响应使用 `Cache-Control: no-store`、`X-Content-Type-Options: nosniff`；API 不重定向到 Provider URL。首切片仅为意外服务错误记录净化调用帧与关联 ID。若增加访问日志，只记录方法、固定路由类型、状态、随机关联 ID 与耗时，不记录 Authorization、正文、查询参数或绝对路径。
 
@@ -24,27 +35,41 @@ Bearer、Host/Origin 与 CSP 是不同边界，不能相互替代。静态预览
 
 ## 3. 有限路由
 
-下列除 Operation 外的 GET 路由已实现，并支持同样鉴权的 HEAD；I4B 只实现 images/runs 两个 POST，其他 POST 与 Operation 查询仍是提案。JSON 响应含 `contractVersion: 0`；列表最多 30 项，摘要不含 Prompt；创建 JSON 上限 64 KiB，Prompt 使用现行生成输入约束。未知/重复查询参数和带正文的只读请求拒绝。
+实验性公开插件工作台可通过 `allowedOperations` 开启持久 `plugin.execute`；媒体执行仍独立开关。它增加以下有限路由，逐请求核对 scope/tools/准确依赖，插件处理器只能调用已声明的 Core 子集；不是通用命令转发。
+
+| 方法与路径 | 输入 | 语义 |
+|---|---|---|
+| `GET /plugin-operations/catalog` | `offset`、`limit=1..30` | 当前连接选择的业务、准确依赖、输入 Schema、available及现有图片；分页沿用作品库 offset/total，过滤不支持类型及超过8 MiB的图片，nextOffset用于继续读取 |
+| `POST /plugin-operations` | UUIDv4 `Idempotency-Key`，`{operationId,dependency,input}`，正文最多64 KiB | 202持久回执；同 Key 同输入读原记录，变更冲突。需要 execute和plugin_call，接受及Core命令处检查有效授权 |
+| `GET /plugin-operations` | `limit=1..30`、`cursor` | 按当前准确业务选择过滤后分页的持久历史；owner可读全部，不要求插件实现仍安装 |
+| `GET /operations/:id`、`GET /operations?key=…`、`POST /operations/:id/cancel` | 原 ID/UUID；cancel正文 `{}` | 复用原查询/接回/本地停止，按记录的准确依赖鉴权；新业务结果含Core确认的artifactIds |
+
+会话附 `pluginExecution/pluginOperations` 和允许的 plugins.catalog/plugins.execute 等别名。工作台有内建业务记录页，插件缺失仍可查原作品。启动将遗留在途记录标为 interrupted，不自动重做；业务 succeeded 仅表示处理器返回及Core命令完成。详见[真实业务](CONTACT_SHEET.md)。
+
+下列 GET/HEAD 已有实现，Operation 路由需未发布的显式执行模式；I4B 只含 images/runs 两个 POST，执行模式另含 continue/cancel，selection 需独立 `--allow-selection` 且仅限 owner。JSON 响应含 `contractVersion: 0`；列表最多 30 项，摘要不含 Prompt；创建 JSON 上限 64 KiB，执行/选择/连接 JSON 上限 8 KiB。未知/重复查询参数和带正文的只读请求拒绝。
 
 | 方法与路径 | 输入 | 语义 |
 |---|---|---|
-| `GET /session` | 无 | 返回实例标识、契约版本、允许的操作与输入上限；不返回根路径、Key 或端点 |
+| `GET /session` | 无 | 返回实例标识、契约版本、允许的操作与输入上限；owner 会话另有稳定 rootId（无请求区为 null），默认 Panel 显式选中扩展时附 panelContributions（身份、准确依赖、本站资源 URL）；连接凭据不获此清单，不返回根路径、Key 或端点 |
+| `GET /creation-requests`（未发布） | `kind=image-import/flow-create`、原 UUIDv4 `key` | 仅 owner；默认只读也可核对已有请求，返回 kind/state 与经核验的结果引用或 null，不补写或生成 |
 | `GET /models` | 无 | 返回当前可选的 `modelRef`、显示名和是否支持改图；不会探测 Provider、同步目录或修改用途 |
 | `POST /images`（I4B） | 原始 PNG/JPEG/WebP 字节、匹配的 Content-Type、Idempotency-Key | 本地提交后返回 201 和 Artifact 引用，同 Key 接回返回 200；不接受文件路径、URL、目录或 SVG |
-| `GET /runs` | `cursor`、`limit`，limit 1–30 | 已有流程摘要，不含 Prompt；只读，不观察远端 |
+| `GET /runs` | `cursor`、`limit`，limit 1–30；0.3 alpha源码另有 `selection=all/selected/unselected` | 已有流程摘要，不含 Prompt；只读，不观察远端。先按选择筛选再计算 total/分页，另有 counts 全部/已选/未选计数 |
 | `POST /runs`（I4B） | `{sourceArtifactId, modelRef, prompt, size?}`、Idempotency-Key | 固定 `image-edit/v0` / `n=1`，只保存输入与身份，零生成请求；本地提交后 201，同 Key 接回 200 |
 | `GET /runs/:id` | 无 | 返回下述 FlowView；只读，不创建 Task、补交付或继续步骤 |
-| `POST /runs/:id/continue` | 空 JSON、Idempotency-Key | 显式首次提交、单次观察原任务、补交付或本地比较；不重提已有 Attempt |
-| `POST /runs/:id/selection` | `{artifactId}`、Idempotency-Key | 只接受该 Run 的原图/新版；不触发生成或下载 |
+| `POST /runs/:id/continue`（未发布执行模式） | `{expectedRevision}`、Idempotency-Key | 持久接收后 202，同 Key 200；一次首次提交/观察/补交付/比较，不重提已有 Attempt |
+| `POST /runs/:id/selection`（未发布选择模式） | `{artifactId, expectedRevision}` | 仅 owner；同 writer 核对版本并保存原图/结果选择，返回 200；过期版本 409，不触发生成或下载 |
 | `GET /artifacts/:id/content` | 无 | 按已验证 Artifact ID 和清单读取该根内媒体字节，不接受 path/URL 参数；不写文件 |
 | `GET /runs/:id/download` | 无 | 返回已选择图片的原字节及受控附件名；未选择则冲突，不接受服务器输出路径 |
-| `GET /operations/:id`（待实现） | 无 | 查询本实例操作状态，不能借此继续操作 |
-| `POST /operations/:id/cancel` | 空 JSON | 停止本次排队/等待，幂等；不代表远端生成已撤销或已退款 |
+| `GET /operations/:id`（未发布执行模式） | 无 | 查询持久状态，不能借此继续操作；原 Key 查询和 Run 列表见服务指南 |
+| `POST /operations/:id/cancel`（未发布执行模式） | 空 JSON | 原 ID 幂等停止本地排队/等待，终态落盘后 200；不代表远端已取消或已退款 |
 
 上传累积读取限制使用现有 `MAX_IMPORT_IMAGE_BYTES = 20 MiB`，不能只相信 Content-Length；最终交给 `readImportImage({imageBytes}, signal)` 检查实际格式和静态图片要求。连接关闭、超量与解析失败不留下临时可服务文件，不把 filename 当服务器路径。并发上传上限 1，超过返回忙；用户显式重试复用原 Key。
 
 上传复用现有图片验证与 Artifact 预留 ID 提交；请求与作品在同一次 writer 内保存。当前图片读取/下载仍限 64 MiB，类型 PNG/JPEG/WebP，先检查清单大小再校验内容哈希，最多两个活动读取。大型媒体磁盘流式、Range 和音视频仍待后续。下载不调用服务器本地 `flow.export(output_path)`；浏览器是否保存成功不属于持久 Run 事实。
 
+未发布 HTTP 列表摘要保留 id/recipe/createdAt/modelRef/source，另投影 updatedAt、revision、output/selection 引用（无值为 null），不附 Prompt、Task、供应商绑定或路径；CLI/MCP 列表保持原语义。省略 selection 等于 all，未知/重复参数或不属于筛选结果的 cursor 返回400。图库封面使用 selection，否则 source。
+
 ## 4. FlowView 与操作反馈
 
 浏览器只消费白名单投影，不直接接收磁盘 Run、完整 Task、Attempt、Provider 错误对象或配置。完整详情是用户创作数据，需要认证；摘要不包含 Prompt。
@@ -79,7 +104,7 @@ ID 继续使用当前 `run_` / `task_` / `artifact_` 加 24 位小写十六进
 
 I4B 的上传与创建同步完成本地提交，以 201/200 返回 Artifact/FlowView 和 `idempotentReplay`，不返回持久排队的 202，也不开放 Operation 查询或取消。相同 Key 保证原业务身份与效果；已有 Run 的返回状态可以随真实进度变化，不承诺重放完全相同的响应字节。
 
-后续异步执行拟在持久接收后返回 `202 {contractVersion:0, operationId, runId?}`，状态为 `queued | running | succeeded | failed | interrupted`。GET 轮询只能读取，不能驱动 Provider；原任务的远端观察必须显式点击。实例内拟最多一个活动 writer、8 个等待写操作；同一 Run 已有活动 continue 时，新 Key 返回冲突，同 Key 接回原 Operation。取消直接中止对应控制器，不能排在被取消 writer 后面；停止等待不伪造远端 Task canceled。这些执行/Operation 语义须另行实现和验收，不随 I4B 自动开放。
+未发布执行模式在原子接收后返回 `202 {contractVersion:0, operation, idempotentReplay:false}`；重放返回 200，状态为 `queued | running | succeeded | failed | canceled | interrupted`。GET 不驱动 Provider；每次显式继续至多一次观察。单根最多 8 条 queued/running，同 Run 最多一条；writer 忙时拒绝新接收，不声称已排队。停止直接中止控制器，随后在同 writer 下落盘并返回 200；不伪造远端 Task canceled。此模式不随 I4B 或只读 Web 自动开启。
 
 ## 5. 上传与持久创建幂等（I4B）
 
@@ -96,7 +121,7 @@ I2 保证相同 Run 使用原 Task；I4B 另保证同 Key 创建请求接回原
 7. 新版 writer 和维护入口必须识别请求格式，未知/半初始化请求区拒绝写入。已发布旧程序没有这些新检查，不能靠一个标记保证其拒绝该根；此专用根只支持已验收的 request-aware writer，回退使用完整副本，不删除请求区伪装降级。已提交 Flow/图片仍可只读查看。
 8. 复用现有原子发布和重入能力，验证范围限进程异常退出/SIGKILL；不据此承诺断电、操作系统崩溃或共享存储下的跨文件事务。请求区本身不触发 Provider 目录刷新、探测、生成或任务观察。
 
-后续 continue/Operation 仍需独立的持久接收与中断协议；重启只展示未完成事实，**不能自动重放 continue**。I4B 的本地创建与中断证据不能代替可能计费的执行验收；开始按钮接入实际生成前，仍须补执行接收、未知受理、取消和停机测试。
+未发布 continue/Operation 使用独立 runner 与持久身份，显式启动只记录遗留中断，**不能自动重放 continue**。I4B 创建证据与执行验收分开；Web 的连接管理写入见 [连接契约](CORE_CONNECTIONS.md)。选择复用 Run 原子提交：当前版本的同目标选择不重写，旧版本即使目标相同也冲突；没有持久 Key/选择收据，响应丢失先 GET 核对，见 [持久选择](LOCAL_SELECTION.md)。源码已实现 [原创建 Key 查询、稳定根身份及浏览器恢复](WEB_RECOVERY.md)和真实创作按钮；刷新或找回创建成功均不自动首次执行。
 
 ## 6. 错误与验收
 

package/docs/LOCAL_CREATION.md

@@ -1,5 +1,9 @@
 # 本地上传与流程创建（0.2.7 / I4B）
 
+0.3 alpha源码另支持 [Operation 执行根](LOCAL_OPERATIONS.md)与 [Core 有限执行服务](CORE_SERVICE.md)，需在新空 Flow 根显式 `execution init`，执行另主动开启；上传/创建仍不生成。下文说明已发布 0.2.7 的 v0 初始化流程，各种根不自动转换。
+
+新的 `execution init --image-generation` 使用 v2 容器；owner 可通过 POST `/api/v0/generations` 保存 `{modelRef,prompt,size?,workflowParameters?}`，使用独立的 `generation-create` 原 Key 查询与重放，不接受来源图片。`workflowParameters` 仅用于明确开放槽位的 ComfyUI 模板，并纳入原 Key 和 Run 输入摘要；旧 `/runs` 不接受该字段。旧 `/runs` 创建仍必须提供来源，不能借旧编辑工具调用新能力。见 [独立文生图](IMAGE_GENERATION.md)。
+
 0.2.7 在 [只读本地 API](LOCAL_API.md)之上，增加显式启用的图片上传和固定 Run 创建。两者都只提交本地数据，不生成、不观察任务、不调用 Provider。实际生成仍使用 [Flow CLI](IMAGE_FLOW.md)；执行/取消 API 与真实 Web 接入留到后续。本功能从 npm 0.2.7 起随包分发。
 
 ## 初始化与启用
@@ -31,10 +35,12 @@ dsh-iris api serve --data-root /absolute/path/new-flow-core --token-file /absolu
 
 超限返回 `413 IRIS_API_INPUT_TOO_LARGE`，不创建作品或消费 Key。对尚未结束的上传，先发送完整错误响应，再丢弃剩余正文并关闭连接；不继续缓存正文，连接仍受现有请求/空闲超时和服务停止约束。客户端收到拒绝后应停止上传。
 
-当前没有 `POST /runs/:id/continue`、selection、Operation 查询或取消接口。GET、HEAD、页面刷新和启动不自动执行或补完创建；现有 Demo 仍使用演示传输，尚未连接这个 API。
+已发布 0.2.7 与仅开启 `--allow-local-writes` 时没有 continue、selection、Operation 查询或取消接口。GET、HEAD、页面刷新和启动不自动执行或补完创建；现有 Demo 仍使用演示传输，尚未连接这个 API。
 
 ## 重试、删除与中断
 
+0.3 alpha源码增加 owner-only 的原 Key 只读查询和 session 稳定 rootId，v0/v1 请求区均可读取；prepared 不自动补完，默认只读服务也不创建请求区。浏览器刷新先验证标签页保存的登录，再 GET 核对，详见 [工作台请求恢复](WEB_RECOVERY.md)。此查询不在已发布 npm 0.2.7 中。
+
 请求意图、预留身份、业务提交和完成状态共用同一次 Core writer。跨进程重启、端口变化或 Token 轮换后，同 Key 仍绑定原数据根和原输入；已有 Run 后续执行或选择过，重放返回其当前 FlowView，不回退进度。已有意图不因当前 Provider 配置变化另选模型/端点，未来执行仍遵守原 Flow binding。
 
 意图发布前的输入错误、busy、排队取消或断线不消费 Key；发布后断线不撤销本地提交。未完成上传需要重新提供相同字节；显式同 Key POST 才核对或补完，没有自动后台重放。关闭服务会停止接收和等待，并保留未完成证据。