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

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 beta应用运行时读取图库时，若索引引用的文件缺失且能确认写者仍活跃，返回 `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 beta允许新根初始化保留一类未发布的租约准备文件：名称、完整 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 beta的 [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` 并复核已取字节的摘要，才返回图片。既有作品读取、持久化格式与内容哈希要求保持。
 

package/docs/CORE_SERVICE.md

@@ -0,0 +1,101 @@
+# Core 服务与 harness 接入（0.3 beta）
+
+0.3.0-alpha.1提供单根执行服务、连接授权/握手、正式 MCP stdio/Streamable HTTP、DSH 可选共享 Flow 连接与 [owner 持久选择 API](LOCAL_SELECTION.md)。**稳定 npm 0.2.7 不包含这些入口**；以下使用源码命令，安装beta包后可将 `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)，同时保留图片流程。**beta.1**另有新 v4 根的[文生视频](VIDEO_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 执行根（beta.1视频流程另支持 v4）和有效的显式配置。配置静态校验、启动和连接握手不调用模型。每次明确继续至多调用一次 `flow.continue`：首次提交或检查/补交付原 Task，不持续轮询，不重提已有 Attempt。
+
+第二个执行 Host 无法取得同根 runner 租约；同根可另开只读页面。接收后服务自行收尾，关页或断开 harness 不撤销已接收操作。默认串行模式在 writer 正忙时明确拒绝新接收，调用方保留原 Key 后显式重试，不能假定已排队。
+
+beta.1可显式增加 `--scheduler-config /absolute/private/scheduling.json`，启用[有界媒体调度](MEDIA_SCHEDULING.md)：单根仍只有一个写者，网络等待可重叠，HTTP并发/RPS/远端未结束任务分别限额。短接收与结束事务不等待整次网络请求，原任务查询/下载不被新提交额度阻挡。未配置仍保持上述默认语义，不自动迁移或重提。
+
+也可使用 [连接中心](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)。
+
+beta.1对 HTTP MCP 使用实例共享的4条活动消息预算，覆盖正文读取和媒体响应排空；兼容批次逐条计数、最多4条，繁忙返回429。单正文仍为9 MiB，媒体限额与已受理任务保持；它和[远端媒体调度](MEDIA_SCHEDULING.md)独立，详见[MCP HTTP](MCP.md#http填写-url-和认证)。
+
+## 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。选择音频组（beta.1也包括视频组）会明确拒绝原生桥启动，避免注册尚无附件投影的工具；不影响原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 beta）
+
+现有 `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 beta的正式 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,26 @@
 
 Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安装的Iris版本；发布状态见 [README](../README.md)。
 
+## Iris 0.3.0-beta.1
+
+beta.1沿用下方12个准确DSH宿主版本，新增出口、调度、凭据与Core文生视频等功能不扩大宿主声明。独立Core Web/MCP无需安装DSH；两类入口覆盖见[发行说明](releases/0.3.0-beta.1.md)。安装beta时明确指定：
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.3.0-beta.1
+```
+
+beta.1要求Node.js ≥22.1.0，包声明、Doctor与最低CI使用同一版本。下方alpha及0.2.x说明保留各自历史范围，不代表beta重新完成了全部宿主组合的真实装载验证。
+
+## 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)。
@@ -30,7 +50,7 @@ Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安
 
 0.2.4的历史范围保持两项准确版本。0.2.5按实际接口能力选择桥接，不再按“0.2”版本号启用默认视觉路由；已验证的旧宿主也能精确绑定默认模型、确认图片输入能力并正确处理失败终态。
 
-扩大插件支持不要求现有用户升级DSH。当前Iris Core、CLI和插件要求Node.js ≥ 22.0.0；DSH若要求更高，以宿主为准。保留旧DSH时也需要满足这个Node要求。
+扩大插件支持不要求现有用户升级DSH。Iris 0.2.x及alpha.1的Core、CLI和插件要求Node.js ≥ 22.0.0；DSH若要求更高，以宿主为准。保留旧DSH时也需要满足这个Node要求。
 
 ## 安装与升级
 

package/docs/DSH_CORE_MIGRATION.md

@@ -71,6 +71,8 @@ TTS 是同步完成型，与视频的长轮询不同：一次 submit 内 complet
 
 转写是上传型异步，Profile 独立：音频在 Host/CLI 边界上传到首选候选 Provider 的临时存储（`oss://` 签名地址只进 providerInput，**绝不落 Core 记录**），经受理边界提交后走 Core 长轮询（默认 2.5s/拍），远端成功后正文物化为 `text/plain` 的 `transcript` Artifact（adapter 在 poll 成功时把正文转为 inline-base64，不依赖签名 URL 生命周期）。CLI `run transcribe` 支持 `audio_url`（公网/oss:// 直达）或 `audio_path`（本地文件经同一上传通道）；Agent 工具与工作台转写动作切 Core，完成时结果直接附转写正文。**零 legacy 双写**，旧转写任务继续 legacy 只读兼容。取消沿用 not_supported 如实语义；retry 输入为 `audio_url`（Core 不持久化音频地址，必须由调用方重新提供）。已知边界：临时音频 URL 属于首选候选的账号，failover 到不同账号时该候选会如实失败。真实 Provider 转写 canary 待验收。
 
+以上为该迁移阶段的历史路径。beta.1已将独立 CLI 的本地音频上传移入原 Attempt：先取得写权，再按每个实际候选账号重新上传，不复用首选账号的临时 URL；两段上传支持取消并停止候选链。未改变原 Task 格式、DSH 工具输入或固定音频 Flow 的来源规则，见[CLI 转写说明](HEADLESS_CLI.md)。
+
 ## 本地媒体原语
 
 Core Command Service 已纳入两项确定性、零 Provider 的本地能力：`media.diff` 用 Sharp 生成指标与 `pixel-diff` 热力图 Artifact；`media.frames` 用本机 ffmpeg/ffprobe 返回视频元数据并生成 `video-frame` Artifact。两者均可读取宿主绝对路径；读取既有 Core Artifact 时分别写入 `derived-from` 或 `frame-of` 关系，Manifest 不保存宿主或临时路径。Headless CLI 的 `media diff` / `media frames` 直接消费同一 Command Service，不读取 Provider 配置、不发起网络请求。
@@ -93,6 +95,10 @@ M1 已包含纯契约、调用控制与 Fake Port。0.2.1 完成提示词 M2：D
 
 S2V 数字人已迁移到共享 Core Task/Attempt/Artifact，DSH 与 CLI 在每个候选的 Attempt 内上传首帧和音频，受理未知停止切换，观察阶段不重新上传或提交。HTML 工具/action 共用 `media.html` Command；独立 CLI 显式提供 Chromium Browser Port，DSH 仍使用宿主浏览器，均保存 `html-screenshot` Artifact。
 
+beta.1中，DSH截图必须确认本次随机页面已由Iris的渲染路由GET返回，才接受浏览器PNG；404、其他服务的200页面或仅HEAD不算确认。使用浏览器原导航及认证，不增加独立探测请求；仍只使用公开open/openUrl/screenshot/close。确认的是HTML交付，布局完成仍依赖原等待和浏览器行为，不声称从PNG证明DOM正确。
+
+DSH输入区进度与泡泡角标复用同一份Core活动快照，显示运行、观察暂停和待处理，不把暂停写成运行百分比；与legacy任务同时出现时保留各自事实。快照沿用已有最多2000条记录扫描并标明截断，不依赖最近任务页大小；隐藏、已读异常、已取消历史和重试成功静默均按现有处置过滤。状态SSE及原刷新事件驱动同一订阅，无新增定时器，最后一个座位卸载后清除缓存和监听。
+
 图片生成支持模型级 DashScope/Images/聊天/Responses 协议。聊天编辑以 `source_artifact_id` 读取 Core 静态图片，各候选按自己的输入预算准备副本，新 Task 保存来源 ID，新 Artifact 记录 `derived-from`；来源参与删除/清理引用保护，原图不变。来源预检失败不创建 Task，未知受理不自动重提。
 
 账号/模型/分配管理、发现预览与合并、单模型实测、Task 有界等待、查询分页/过滤、显式批量查询/导出、JSON 文件/stdin 以及 Core 可恢复删除/清理均已实现，详见 [CLI 管理与补齐](CLI_MANAGEMENT.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 beta另可显式连接 [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 工作台；0.3 beta的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

@@ -4,9 +4,9 @@
 
 本文面向 Iris 0.2.7，涵盖无 DSH 的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为 Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core 内部接口与 Artifact v0 尚未冻结为公共 SDK。
 
-需要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需要Node.js ≥22.0.0；beta.1需要≥22.1.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，0.3 beta 的 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)。
 
@@ -20,6 +20,10 @@
 
 ## 配置查询与离线诊断
 
+beta.1另提供 `network init/show/check` 与 `network nodes|pools list/add/set/remove`，只管理独立、显式私有文件；不改变当前出站，也不创建 Core 根或调用模型。用法、修订与引用保护见[出口节点与池](NETWORK_RESOURCES.md)，alpha.1/0.2.7尚不包含此命令。
+
+[N2供应商绑定](NETWORK_ROUTING.md)另有v2文件、新目录包装与实例代理运行时，已完成受控HTTP/HTTPS代理、真实CLI/API及原任务跨进程恢复验证。[N3网络工作台](NETWORK_WORKBENCH.md)已接Web管理与Core进程内Doctor，需 `api/web serve --allow-network-management --network-config <private-file>`；均属beta.1，普通MCP不获得管理权限。
+
 ```bash
 dsh-iris providers list --provider-config /absolute/path/to/providers.json
 dsh-iris capabilities list --provider-config /absolute/path/to/providers.json
@@ -32,7 +36,9 @@ 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：
+当前源码的 `api/web serve` 还可显式使用 `--scheduler-config <absolute-private-json>`，详情见[有界媒体调度](MEDIA_SCHEDULING.md)。这不是单次 CLI 或独立 DSH 路径的并发开关；未配置保持原行为。
+
+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
@@ -74,6 +80,8 @@ dsh-iris media frames \
 
 ## Provider 图片生成
 
+当前源码另支持显式[环境凭据引用](PROVIDER_CREDENTIALS.md)：配置保存 `apiKeyEnv` 名称，值来自当前 Core/CLI 进程；已发布 alpha.1/0.2.7 尚不支持，原 `apiKey` 配置保持。
+
 CLI 必须同时收到显式 Core 数据根和私有供应商配置文件，不推断 DSH、HOME 或 cwd：
 
 ```bash
@@ -122,7 +130,7 @@ dsh-iris run transcribe \
   --data-root /absolute/path/to/iris-data \
   --provider-config /absolute/path/to/providers.json \
   --input '{"audio_url":"https://example.com/public.wav"}'
-# 或本地文件（经首选候选 Provider 的临时存储上传）：
+# 或本地文件（经实际候选 Provider 的临时存储上传）：
 dsh-iris run transcribe \
   --data-root /absolute/path/to/iris-data \
   --provider-config /absolute/path/to/providers.json \
@@ -131,6 +139,8 @@ dsh-iris run transcribe \
 
 输入冻结为 `{audio_url | audio_path, model_ref?}`（二选一）：`audio_url` 必须是 `https://` 或 `oss://`；`audio_path` 在命令内先上传为临时 `oss://` 地址再提交——**签名/临时 URL 绝不写入 Core 记录**。受理后由显式 `task observe` 逐拍推进；远端成功后正文物化为 `text/plain` 的 `transcript` Artifact（`artifact inspect/export` 可直接读取/导出文本）。终态失败可用 `task retry --input '{"audio_url":"..."}' --confirm-billing` 显式重试为新任务。
 
+beta.1在取得写权并保存原 Task/Attempt 后才上传本地音频；根忙不上传。每个候选使用自身账号重新准备输入，两段上传都响应取消；实际上传失败写入原 Attempt，取消后不继续候选。命令返回 Task 结果时应检查 `acceptance/outcome/lastError`，进程退出0不单独表示生成成功；静态不支持上传仍返回 `IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED`，不建立 Task。
+
 ## 检查 Task 与 Artifact
 
 Task 查询是纯 reader，不需要 Provider 配置，也不会触发 submit、poll、恢复或下载：
@@ -162,6 +172,10 @@ dsh-iris task observe task_0123456789abcdef01234567 \
 
 同一份"显式单步观察、绝不重新提交"也已在 DSH 侧开放：工作台 API 提供 `POST /iris/api/core/task/:id/reobserve`，用户任务区的 Core 投影行和高级诊断卡提供「重新观察」按钮。三者经同一个 Command Service 命令（对外命令名 `task.reobserve`，实现与 `task.observe` 相同），共用原 Provider/binding 校验；每次调用至多一次 poll，对终态、未受理、无远端 ID 或 binding 漂移的任务在网络前拒绝。
 
+beta.1补齐两处恢复边界：Core/Flow 恢复和 DSH 启动接管遇到已明确 `not_accepted`、但最终失败尚未落盘的任务时，按原 Attempt 和安全错误收口为失败；不尝试下一候选、不重新生成。纯 reader 查询仍只读，不暗中恢复记录。
+
+DSH 启动恢复旧 `tasks.json` 时，先解析当次宿主连接引用，再按任务原协议和远端 ID 观察；连接暂不可用则保留原记录及原因，恢复连接后可在下次启动接管，仍受既有观察窗口限制。保持旧格式，不自动迁入 Core 根，也不自动翻转已被旧版本标为失败的记录。旧任务缺少 Core 的端点 binding 保护，不能据此保证历史端点变更后的身份校验。
+
 已成功但本地产物取回失败（deliveryState=failed）的 Task 可以显式重新取回，绝不重新生成：
 
 ```bash
@@ -197,7 +211,18 @@ dsh-iris task retry task_0123456789abcdef01234567 \
 
 缺 `--confirm-billing` 时在网络与创建之前拒绝。候选链按当前 assignments/池实况重新解析（不绑定旧 Provider/binding——旧配置可能正是失败原因），`--model-ref` 可显式指定。新 Task 有全新 id、attempts 与提交时实况 binding，并记录单向 `retriedFrom` 指向旧 Task；旧 Task 零变化。**Task 记录不持久化 Prompt**，所以生成指令必须由 `--input` 重新提供，绝不从旧任务恢复。DSH 侧同构开放：`POST /iris/api/core/task/:id/retry`（请求体必须 `confirmBilling:true`）与工作台「重试为新任务」按钮（重新输入指令 + 重复计费确认弹窗）。
 
-重试输入按旧 Task 的能力校验：图片为 `{prompt, size?, n?}`，视频为 `{prompt, size?, duration?, img_data_url?}`，TTS 为 `{text, voice?}`，转写为 `{audio_url}`。视频首帧和转写地址会转换为 Provider 所需字段；原任务中的媒体输入不会自动恢复。转写 retry 要求重新提供 HTTPS/OSS 地址，本地 `audio_path` 上传仍通过正常提交入口处理；模型覆盖使用外层 `--model-ref`，不放在 retry 的 `--input` 中。
+重试输入按旧 Task 的能力校验：图片为 `{prompt, size?, n?}`，TTS 为 `{text, voice?}`，转写为 `{audio_url}`。转写 retry 要求重新提供 HTTPS/OSS 地址，本地 `audio_path` 上传仍通过正常提交入口处理；模型覆盖使用外层 `--model-ref`，不放在 retry 的 `--input` 中。
+
+beta.1中的视频重试必须另外在 `--input` 中明确 `video_mode`（`t2v/i2v/s2v`）：t2v 重新填写提示词；i2v 还需 `img_data_url` 或绝对 `first_frame_path`；s2v 需绝对 `first_frame_path`、`audio_path`，可选 `resolution`。所选模式与媒体输入冲突、缺失时在解析候选和创建新 Task 前拒绝，不从旧模型名推测模式，不静默转为 t2v。此控制字段仅用于 `task retry`，不发送给供应商、不保存到旧 Task，也不用于 `run video` 或固定文生视频 Flow。DSH 简化按钮改为「重新创建文生视频」，须先明确输入 t2v；HTTP 请求须带 `video_mode:"t2v"`。图生/数字人视频通过完整视频工具或 CLI 重新提供来源，简化 HTTP 入口拒绝媒体字段，不读取服务器文件。
+
+```bash
+dsh-iris task retry task_0123456789abcdef01234567 \
+  --data-root /absolute/path/to/iris-data \
+  --provider-config /absolute/path/to/providers.json \
+  --model-ref providerId::i2v-model \
+  --input '{"video_mode":"i2v","prompt":"重新输入的视频指令","first_frame_path":"/absolute/path/to/frame.png"}' \
+  --confirm-billing
+```
 
 CLI、DSH 正常生成与 retry 共用输入规范：Prompt/文本修剪后为 1–20000 字符，图片 `n` 为 1–4 的整数（缺省 1），视频时长为 1–60 的数字，规范化后的显式 size/voice 为 1–64 字符。转写地址修剪后最多 20000 字符。数字字符串会转为数字；非法生成参数在提交前拒绝，不创建新的计费 Task。CLI 和 retry 还会拒绝未知输入字段；DSH 保留自己的宿主参数，由入口提取生成参数，工作台清空可选文本框仍使用默认值。
 

package/docs/HOST_ADAPTER_CONTRACT.md

@@ -8,6 +8,8 @@ Iris 0.2.6 增加 [三种功能池策略](FUNCTION_MODEL_POOLS.md)；下文“
 
 Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、会话、浏览器和模型能力映射为 Iris 端口。Command 接收 Iris 输入、`AbortSignal` 和所声明的 Host Port，**不得接收原始 `ctx`**。Task、Provider、文件持久化和成本语义不属于宿主。
 
+DSH的`/client`是浏览器ModuleLoader注册入口，运行时不提供Node默认导出。beta.1声明通过`import type { DshClientPlugin } from '@mokuyoaxis/dsh-iris/client'`描述宿主获得的工厂形状；该类型可由strict NodeNext消费，不会把浏览器bundle伪装成可在Node直接加载的插件对象。Core插件作者继续使用`/plugins`公共SDK。
+
 契约版本固定为 `0`。它仍是内部接口；只有经过 DSH 与 Local Host 两个真实消费者验证后，才考虑成为公开 SDK。
 
 ## 端口清单
@@ -19,7 +21,7 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | `clientSlots` | Web Client `ctx.slots` | 注册设置、输入区、dock 与 overlay 座位 | 服务端任务和 CLI 不受影响 |
 | `skills` | `ctx.skills` | 注册随包 Skill，声明用户/模型调用策略 | 工具仍可直接调用；Doctor 给出降级原因 |
 | `attachments` | `ctx.get('attachments')` | 保存/读取图片字节，返回 Iris 自有引用 DTO | DSH 图片投影或会话图片读取不可用 |
-| `sessions` | `ctx.get('sessionQuery')` / Client sessions | 列出当前会话的受支持附件和最小模型选择信息 | 只使用 Iris 自有产物或显式上传 |
+| `sessions` | `ctx.get('sessionQuery')` | 读取会话并列出/定位受支持的图片附件 | 只使用 Iris 自有产物或显式上传 |
 | `browser` | `ctx.get('browser')` | 将受限 HTML 渲染为图片；不向 Command 暴露 DSH page/session 对象 | HTML 截图不可用 |
 | `textModel` | DSH LLM/default-model 服务 | 文本生成及精确模型元数据；当前宿主视觉也由此绑定默认选择 | 宿主文本/视觉不可用，自持 Provider 按各功能名单执行 |
 | `providerConnections`（0.2.6） | DSH LLM 目录、settings 与 credentials 服务 | 列出无密钥的连接元数据；仅在服务端操作期间解析所引用连接 | 连接引用不可用，手动供应商不受影响 |
@@ -38,12 +40,12 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | `look`、`locate`、`ocr` | 无 | `textModel` + `attachments` | 只按视觉名单尝试自持或显式宿主资源，无可用项时失败 |
 | `crop`、`diff`、`video_frames` | 无 | 无 | 确定性本地动作 |
 | `media_summarize` | 无 | `textModel` + `attachments` | 帧提取是本地动作，理解阶段只使用视觉名单 |
-| `html` | `browser` | 无 | Command 只调用语义级 `renderHtml` |
+| `html` | `browser` | 无 | Command只调用语义级`renderHtml`；DSH实现还须确认本次HTML经Iris路由GET完成，独立Chromium不依赖宿主路由 |
 | `relook` | 条件必需 `attachments` + `sessions` | 无 | Iris 自有附件可直接解析；会话附件必须走宿主端口 |
 | `attachments_list`、`attachment_export` | 条件必需 `attachments` + `sessions` | 无 | Iris 自有产物不依赖宿主；会话来源不得读取宿主私有文件 |
 | Task 查询、观察、交付、提醒和知情重试 | 无 | 无 | 事实、费用确认和新旧 Task 关系归 Iris 所有 |
 | Provider/模型/能力配置 | 无 | 无 | 普通发现与配置不依赖宿主；手动实测只调用指定Provider，不按生产名单或回退宿主 |
-| Prompt Optimize | `textModel` | `sessions` | 客户端可显式传模型；否则从宿主获取当前/默认选择 |
+| Prompt Optimize | `textModel` | 无 | 客户端可显式传模型；否则经`textModel.currentSelection()`解析当前/默认选择，不依赖`sessions` |
 | DSH 工具结果投影 | `tools` | `attachments` | 注册与结果转为 DSH attachment 属于 DSH Adapter，不进入 Command |
 | Workbench/API/媒体路由 | `routes` | `clientSlots` | HTTP/UI 只是投影，不是真相来源 |
 | 随包 Skill | `skills` | 无 | Skill 不得绕过 Command、Task 或费用边界 |

package/docs/IMAGE_FLOW.md

@@ -1,5 +1,9 @@
 # 固定图片流程（0.2.7）
 
+0.3 beta另提供 [image-generate/v0 与 ComfyUI 入口](IMAGE_GENERATION.md)，需显式的新 v2 执行根；下文保留 0.2.7 的原固定编辑流程，旧根不自动迁移。
+
+0.3 beta可通过 [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 的导出路径暴露给浏览器。