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

package/docs/CORE_RUNTIME_CONTRACT.md

@@ -1,6 +1,6 @@
 # Core Runtime v0 内部契约
 
-本文定义 Iris 0.2.2 沿用的 Core Runtime 内部接口，初版在 0.2.0 实现。内部接口在后续版本仍可能调整，npm 包不把它作为公开 API 导出；现有 `config.js`、`tasks.js` 和 `artifacts.js` 也尚未迁移。
+本文定义 Iris 0.2.x 沿用的 Core Runtime 内部接口，初版在 0.2.0 实现。内部接口在后续版本仍可能调整，npm 包不把它作为公开 API 导出；现有 `config.js`、`tasks.js` 和 `artifacts.js` 也尚未迁移。
 
 ## 目标与范围
 
@@ -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 不纳入这些新增保证。
@@ -72,6 +75,39 @@ created --start--> started --dispose--> disposing --finish-dispose--> disposed
 
 错误、Doctor 证据和 Command 输出不得包含 API Key、授权头、私有签名 URL 或不必要的本机绝对路径。Core 的 Artifact 结果使用稳定 ID 和中性元数据；HTTP/media URL、DSH attachment 与会话展示均由 Host Adapter 投影。
 
+## 应用运行时装配
+
+[application-runtime.js](../lib/application-runtime.js)是 0.3 的内部基础，复用上述 Core，不新增公开 export。实例显式接收数据根，以及可选的图片候选和既有任务 Adapter 解析函数；构造、状态查询和空闲期间不创建目录、持有租约或调用 Provider。首批 CLI 图片生成、图片导入、差异分析、作品查询/导出和单项 Task 查询已接入；DSH 的 Core 装配也已接入实例队列，其他 CLI 命令继续沿用原入口。
+
+- 同一应用实例的写操作按 FIFO 执行；每次写操作独立创建、释放 Core writer，普通失败原样返回，后续项继续。实例之间不共享队列或取消状态，跨进程写冲突仍返回 busy。
+- reader 独立于写队列，只读取已提交事实；它不调用配置解析函数或 Provider，不创建缺失数据根。并发写入时，多次读取不构成整个工作区的一致快照。
+- 排队输入保存为本次操作的快照。开始前取消跳过该项，不解析候选、不创建 Task；执行中取消传播到本次 Core。已经保存的结果按真实事实返回，未知受理不重新生成，本地中止不等于远端已取消。
+- `dispose()` 拒绝新操作和未开始项、中止活动操作，并等待业务回调和 Core 释放；重复调用返回同一个过程。租约释放失败时保留错误和现场，停止后续执行，不能报告关闭成功。
+
+首批执行面包括图片生成/改图、`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` 记录 Run 与步骤，旧记录不批量改写。已有 Attempt 后继续操作只核对原事实、观察或补交付，不重新 submit；完整异步 Flow 结果也先缓存，再按原 Artifact ID 交付。原图和流程作品/Task 同步纳入删除保护。0.3 alpha源码的 [HTTP 执行与本地停止](CORE_SERVICE.md)、[owner 选择](LOCAL_SELECTION.md)复用上述实例；通用 Recipe 与 DSH Flow 界面仍待完成。
+
+## DSH Adapter 与实例装配的当前边界
+
+[dsh-host-adapter.js](../lib/dsh-host-adapter.js)从宿主公开服务构造附件、Browser、模型、连接和路由等端口；[dsh-core-adapter.js](../lib/dsh-core-adapter.js)选择 `irisHome()/core-v0`，将宿主输入转成共享 Command/Task Runner 调用，再投影为附件字节、媒体路由和任务展示。DSH 直接调用本地 Core，不经过独立 HTTP API。
+
+`apply(ctx)` 现在持有一个 `createDshRuntime({ dataRoot, getHost })`，工具、动作和工作台显式使用该实例；Core 写入共用上述 Application Runtime，连接端口引用、观察器和启动接管归实例所有。内部 `run(reader|writer, callback)` 允许 DSH 复合操作复用既有业务，不作为 HTTP 或公开 SDK。卸载拒绝新调用、取消并等待在途操作与租约释放；失败保留现场，旧观察回调不能影响新实例。详见 [DSH 实例运行时](DSH_RUNTIME.md)。
+
+legacy 配置/任务/作品、上传与 SSE 仍保留原机制，不宣称同进程多 profile 完整隔离。固定 Flow 未接入 DSH 工作台，新增本地请求区不会自动创建或迁移 DSH 日常根。
+
+## 显式本地 HTTP Host
+
+[local-api.js](../lib/local-api.js)由 CLI `api serve` 显式装配，只监听 loopback，默认使用已有 Flow 根与 reader 提供受控读取；构造不做 I/O，默认启动/关闭不持有 writer。默认路径只调用 `flow.list/inspect` 和作品只读入口，没有生成或远端观察 resolver。身份、Host/Origin、媒体限额与受控 DTO 属于该 Host 的边界，不借用 DSH 登录或通用 Command 转发；使用见 [只读本地 API](LOCAL_API.md)。
+
+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 保持。
+
+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` 并复核已取字节的摘要，才返回图片。既有作品读取、持久化格式与内容哈希要求保持。
+
 ## 当前接口与后续范围
 
 0.2.3 增加同步完成结果的私有交付缓存：`task.redeliver` 可从原结果恢复，无需虚构远端 ID；完整字节离线交付，缺失字节只取回原 URL，不 submit。完整缓存可补回提交完成事实的中断，预留 Artifact ID 支持逐件重入；缓存与任务隔离/恢复一起管理。详见 [同步交付恢复](SYNC_DELIVERY_RECOVERY.md)。
@@ -80,7 +116,7 @@ created --start--> started --dispose--> disposing --finish-dispose--> disposed
 
 - `normalizeCoreOptions()`：规范化显式数据根和 reader/writer 模式；
 - `createCoreRuntime()`：管理写者租约、状态、`AbortSignal`、在途操作和 cleanup；
-- `createCommandService()`：提供 `crop`、只读 `task.list/task.inspect`、显式单步 `task.observe`/`task.reobserve`（同一份实现，`reobserve` 是人工触发观察的对外命令名）、人工重新交付 `task.redeliver`（只开放 outcome=succeeded / deliveryState=failed，异步使用一次带 redelivery 标志的 re-poll + 下载，同步结果使用原缓存，绝不 submit、绝不重新生成）、人工取消 `task.cancel`（只开放已受理未终态任务，只有 Provider 明确确认才写 canceled，不支持/无法确认保持真实状态）、人工重试为新任务 `task.retry`（只开放终态未成功交付任务；必须显式 confirm_billing 确认重复计费；新 Task 记录单向 retriedFrom 关系，候选链按宿主实况重新解析；Core 不持久化 Prompt，prompt 必须由调用方重新提供），以及 Artifact inspect/list/export/rebuild；Task reader 返回既有安全事实，不读取 Provider 配置，也不创建、修复或迁移记录；需联网的 `observe/reobserve/redeliver/cancel` 只接受宿主注入的 Adapter resolver；完整本地缓存的 redeliver 不解析 Provider，`retry` 只接受宿主注入的候选链 resolver，Core 不读取配置路径；Task capability覆盖image、video、tts、transcribe与music——交付按 `provider-task-runner.js` 的 DELIVERY_PROFILES 冻结（video：`video/mp4` + `generated-video`；tts/music：`audio/mpeg`/`audio/wav` + `generated-audio`，同步 completed 同次调用内交付；transcribe：`text/plain` + `transcript`，正文物化为 UTF-8 Artifact），不共用不准确的图片交付语义；
+- `createCommandService()`：提供 `crop`、只读 `task.list/task.inspect`、显式单步 `task.observe`/`task.reobserve`（同一份实现，`reobserve` 是人工触发观察的对外命令名）、人工重新交付 `task.redeliver`（只开放 outcome=succeeded / deliveryState=failed，已有缓存使用原结果，未缓存的异步任务使用一次带 redelivery 标志的 re-poll + 下载，绝不 submit、绝不重新生成）、人工取消 `task.cancel`（只开放已受理未终态任务，只有 Provider 明确确认才写 canceled，不支持/无法确认保持真实状态）、人工重试为新任务 `task.retry`（只开放终态未成功交付任务；必须显式 confirm_billing 确认重复计费；新 Task 记录单向 retriedFrom 关系，候选链按宿主实况重新解析；Task 不持久化 Prompt，prompt 必须由调用方重新提供），以及 Artifact inspect/list/export/rebuild；Task reader 返回既有安全事实，不读取 Provider 配置，也不创建、修复或迁移记录；需联网的 `observe/reobserve/redeliver/cancel` 只接受宿主注入的 Adapter resolver；完整本地缓存的 redeliver 不解析 Provider，`retry` 只接受宿主注入的候选链 resolver，Core 不读取配置路径；Task capability覆盖image、video、tts、transcribe与music——交付按 `provider-task-runner.js` 的 DELIVERY_PROFILES 冻结（video：`video/mp4` + `generated-video`；tts/music：`audio/mpeg`/`audio/wav` + `generated-audio`，同步 completed 同次调用内交付；transcribe：`text/plain` + `transcript`，正文物化为 UTF-8 Artifact），不共用不准确的图片交付语义；
 - 0.2.1 补齐 `media.diff/frames/html`、S2V 按候选上传、查询/批量管理与 Core 隔离/恢复；视觉和维护入口见 [CLI 管理](CLI_MANAGEMENT.md) 与 [视觉 CLI](VISION_CLI.md)。
 - Artifact Manifest v0：保存受控对象、SHA-256、关系边和可重建 Index，可跨 CLI 进程检查、导出和显式重建；Doctor 只报告孤立/未解析条目，不自动删除或修复。
 
@@ -88,7 +124,7 @@ created --start--> started --dispose--> disposing --finish-dispose--> disposed
 
 ## 非目标
 
-- 当前接口尚未作为 package export 或第三方 SDK 发布。0.2.0 的 F 阶段已正式决定：**不新增 `./core` 公开 export**——Root 插件与 `bin/dsh-iris` CLI 承载全部对外能力，内部模块（core-runtime、core-tasks、command-service、provider-task-runner、core-artifact*、core-user-projection）保持私有，可在 minor 版本间调整；冻结为公开 export 的决策顺延到 M2（0.3.0）的 Recipe/Serve 边界定稿后再审。届时一旦公开即写兼容策略与 semver 边界；
-- 不提供 standalone 服务、账号、多租户或额外监听端口；
-- 不预建缺少实际需求的 Provider 协议；收藏、标签、搜索与 Flow/Recipe 留待后续；
+- 当前接口尚未作为 package export 或第三方 SDK 发布。0.2.0 的 F 阶段已决定**不新增 `./core` 公开 export**：Root 插件与 `bin/dsh-iris` CLI 承载对外能力，内部模块保持私有，可在后续版本调整。按 [现行路线图](ROADMAP.md#03-及以后)，公开 Provider/Host SDK 在 0.4 有真实消费者后再评估；0.3 的 Recipe/API 实现不自动构成公开 SDK 或兼容承诺。
+- Core 本身不启动监听；0.2.7 的 HTTP Host 由用户显式启动，默认只读、本地创建另行启用，不建设账号、多租户或公网 SaaS；
+- 不预建缺少实际需求的 Provider 协议；收藏、标签、搜索与通用 Flow/Recipe 留待后续；
 - 不把 0.1.4 的模块级存储包装成实例存储，也不允许 CLI 与 DSH 无租约并发写同一数据根。

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

@@ -0,0 +1,94 @@
+# Iris Core Skill · 宿主无关的图片工作流
+
+0.2.7 新增 [`iris-core`](../skills/iris-core/SKILL.md)，指导 Agent 使用现有独立 CLI 导入、生成、编辑图片，查询原任务并取回作品。正文使用英文、标题附中文；参数与任务恢复按需阅读配套参考。它不需要运行 DSH，也不依赖某个个人账号、模型或目录。
+
+本 Skill 从 npm 0.2.7 起随包分发。CLI 命令本身已有实现；安装了 CLI 不代表宿主已经发现 Skill，加载了 Skill 也不代表媒体模型已经配置。
+
+## 显式安装、检查与卸载
+
+0.2.7 的安装器随 npm 包中的 CLI 和 `lib/` 一起分发，从当前执行的包定位 Skill，不依赖仓库 cwd、全局 node_modules 固定位置或临时软链。没有 npm `postinstall`，安装 npm 包本身不会写其他 harness 的目录。
+
+```bash
+dsh-iris skills install --target kimi --dry-run
+dsh-iris skills install --target kimi
+dsh-iris skills status --target kimi
+```
+
+`--target kimi` 使用 `$KIMI_CODE_HOME/skills`，未设置时使用 `~/.kimi-code/skills`。自定义目录可单独使用，也可覆盖 Kimi 默认位置；它指向包含 Skill 子目录的扫描根，不是 `iris-core/` 本身：
+
+```bash
+dsh-iris skills install --directory /absolute/path/project/.agents/skills
+dsh-iris skills status --directory /absolute/path/project/.agents/skills
+```
+
+安装器复制整个 `iris-core/`，不自动修改模型、MCP、宿主设置或 DSH Skill registry。其他 harness 需要由用户明确提供其支持的扫描目录；目录布局正确仍需在该宿主复核发现与调用。`--dry-run` 仅预览，不创建目标、控制目录或锁；`status` 始终只读。
+
+安装目录中的 `.iris-install.json` 记录包名、版本、文件摘要及目录清单。重复安装当前副本不写入；显式再次安装可更新内容完整且未经本地修改的旧副本，即使包版本相同也会比较内容。已有目录无有效记录、存在额外/缺失/改动文件或目录、包含软链时保留现场并报告冲突，不提供强制覆盖。
+
+升级前将原目录完整移到扫描根之外的同级 `.iris-skill-installs/<目录摘要>/backup-*/iris-core`，再排他创建新目录。复制失败时保留旧备份及新目录现场；不自动覆盖恢复，也不接管无完整记录的半成品。控制目录的锁异常同样保留，需人工核对，不自动清理。
+
+卸载也只处理归属有效、内容未改动的副本，移动到上述备份区并返回 `backupPath`，不永久删除，不清理备份：
+
+```bash
+dsh-iris skills uninstall --target kimi --dry-run
+dsh-iris skills uninstall --target kimi
+```
+
+`status` 为 `current` 时 exit 0，`not_installed`、`update_available`、`modified` 或 `unmanaged` 为 exit 1；参数错误为 exit 2。输出的 `discovery: not_checked` 明确表示没有启动宿主检查其技能列表。安装完整性、宿主实际发现、Agent 按 Skill 完成创作分别验收；安装/状态/卸载不调用模型或媒体供应商。
+
+## 文件与装载
+
+`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 的环境中独立验证：
+
+```bash
+kimi --skills-dir /absolute/path/to/iris/skills
+```
+
+这会为本次启动指定 Skill 目录；不自动修改日常配置。搜索优先级、同名覆盖和调用方式以当前宿主版本为准。Kimi 的目录形式与参考资源说明见[官方文档](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/skills.html)，通用目录约定见 [Agent Skills 规范](https://agentskills.io/specification)。
+
+宿主读取 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#dsh-插件027)。
+- 本版新增独立的 Core 指导，不迁移或改写旧 DSH Skill。后续若合并公共参考，应先证明 DSH 流程和资源解析保持。
+- Core Artifact ID 属于指定根，宿主附件、路径与 URL 不可互换；交付时由实际宿主呈现导出文件。
+- 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,9 +2,19 @@
 
 Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安装的Iris版本；发布状态见 [README](../README.md)。
 
-## Iris 0.2.6
+## Iris 0.3.0-alpha.1
 
-0.2.6 沿用 0.2.5 的以下 12 个准确版本声明，不因连接复用扩大宿主支持范围。连接引用另需供应商目录、脱敏设置及凭据公开服务；缺少接口时使用手动供应商。首次配置与升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
+本次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)。
 
 ## 0.2.5 建立的兼容范围
 
@@ -34,10 +44,10 @@ Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安
 
 ## 安装与升级
 
-在上述 12 个准确版本的宿主中，固定安装 Iris 0.2.6：
+在上述 12 个准确版本的宿主中，固定安装 Iris 0.2.7：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7
 ```
 
 使用其他profile时替换 `web`。更新后检查服务端装载、刷新Web客户端，并查看Iris工作台的 [宿主诊断](HOST_DOCTOR.md)。alpha.3及之后的DSH改善了插件更新与热加载，但仍以实际装载结果为准。

package/docs/DSH_CORE_MIGRATION.md

@@ -4,6 +4,8 @@ Iris 0.2.3 的音乐生成由 CLI、Agent 工具与工作台共同调用，使
 
 本文描述 **Iris 0.2.2** 的实现边界；0.2.0 建立的 Core 数据格式保持兼容。迁移逐条切换消费者，不原地改写 0.1.4 数据。
 
+0.2.7 已进一步完成 [DSH 实例装配](DSH_RUNTIME.md)：插件持有 Core 写队列、连接端口引用和观察器，卸载等待在途操作及释放。既有业务与数据格式保持；下文各版本验收记录仍按当时范围解读。
+
 0.2.1 已把 S2V、HTML、单图视觉、OCR、定位、摘要和提示词预览接入共享 Core Command 或 Model Ports，并补齐视觉 CLI、配置/查询/维护命令。图片按模型选择四种协议，Artifact ID 聊天编辑另存新作品并保留来源关系；输入预算仅处理发送副本。功能范围见 [发布说明](releases/0.2.1.md)。
 
 ## 已切换的执行链：本地媒体处理与新生成任务
@@ -11,7 +13,7 @@ Iris 0.2.3 的音乐生成由 CLI、Agent 工具与工作台共同调用，使
 - `iris_crop` 和工作台 crop 共用 Command Service 与 Artifact Manifest。attachment 输入先成为 `host-input` Artifact，裁剪结果用 `derived-from` 保存关系；工具名、参数和附件输出不变。
 - 新图片任务的同步、异步与混合候选均使用同一 Core Task/Attempt/Artifact。每个候选先落盘 Attempt，只有明确 `not_accepted` 才允许切换；收到远端 ID 或受理未知后停止候选提交。
 - 新 Attempt 可选记录七个单调 `stageTimestamps` 边界，区分排队、提交、远端执行、下载和本地 Artifact 处理；旧记录缺失该字段仍合法，未发生的阶段不补写。
-- Provider 只收到原始模型 ID；Core 保存 `providerId::modelId` 和非敏感端点 binding，不保存 Prompt、凭据、下载 URL 或 DSH 会话。
+- Provider 只收到原始模型 ID；Task 保存 `providerId::modelId` 和非敏感端点 binding，不保存 Prompt、凭据、下载 URL 或 DSH 会话。0.2.7 的 [固定流程](IMAGE_FLOW.md)将提示词保存为专用根的私有 Run 输入，不改变 Task 的隐私边界。
 - DSH 边界选择 `$DSH_HOME/iris/v1/core-v0`，与旧 `tasks.json`、`artifacts.json`、`outputs/` 隔离。旧任务仍由旧观察器读取和接管；新图片不双写旧存储。
 
 `iris_draw_image` 等待同一 Core Task，ready 后通过命名 Attachment Port 返回图片。等待超时只返回稳定 Task ID，后台观察继续；停止工具等待不等于远端取消。宿主投影失败不会撤销 Core 中已经成功交付的产物。
@@ -37,7 +39,7 @@ DSH 工作台现也开放同一份显式单步观察（D1 reobserve）：`POST /
 
 人工控制面第三项 cancel（D3）同样开放：`POST /iris/api/core/task/:id/cancel` 与 CLI `task cancel` 经 Command Service 命令 `task.cancel`，只对已受理、有远端 ID、未终态且未请求过取消的 Task 开放。结果只有三种，且**绝不伪造已取消**：① 供应商明确确认 → outcome=canceled、cancelState=remote_confirmed；② 供应商不支持远端取消（当前 DashScope 与 OpenAI Images 媒体协议均不提供经过验证的取消实现）→ 取消未发生，回落到可继续观察的真实状态（outcome 不变）；③ 超时或网络失败 → cancelState=unknown、保持非终态，可显式 reobserve 收敛。竞态下远端先沉淀的成功事实不得被取消覆盖；已请求过取消但未确认的任务拒绝再次取消。工作台按钮「取消任务」需要二次确认，五类用户状态保持不变，三种结果态在高级诊断的「取消状态」字段如实区分（已确认 / 已请求未确认 / 无请求）。
 
-人工控制面最后一项 retry as new task（D4）也已开放，控制面四个动作全部收口：`POST /iris/api/core/task/:id/retry` 与 CLI `task retry` 经 Command Service 命令 `task.retry`。这是唯一产生新的真实计费的动作，三层都强制显式确认——CLI `--confirm-billing`、API 请求体 `confirmBilling:true`、UI 含重复计费警示的确认弹窗，缺一不进且在网络与创建之前拒绝。只对终态且未成功交付的 Task 开放（succeeded+ready 拒绝）。新 Task 有全新 id/attempts/binding，候选链按当前 assignments/池实况重新解析（旧 binding 可能正是失败原因），`model_ref`/`modelRef` 可显式指定；记录单向 `retriedFrom` 关系指向旧 Task，旧 Task 事实零变化，高级诊断以「重试来源」展示该关系。**Core 记录不持久化 Prompt**，生成指令必须由调用方重新提供（CLI `--input` / API `prompt` / 工作台弹窗重新输入），绝不从旧任务"恢复"——这是隐私设计，不是缺陷。同一请求网络重放的幂等键未实现：每次显式确认即一个新任务，属预期语义。
+人工控制面最后一项 retry as new task（D4）也已开放，控制面四个动作全部收口：`POST /iris/api/core/task/:id/retry` 与 CLI `task retry` 经 Command Service 命令 `task.retry`。这是唯一产生新的真实计费的动作，三层都强制显式确认——CLI `--confirm-billing`、API 请求体 `confirmBilling:true`、UI 含重复计费警示的确认弹窗，缺一不进且在网络与创建之前拒绝。只对终态且未成功交付的 Task 开放（succeeded+ready 拒绝）。新 Task 有全新 id/attempts/binding，候选链按当前 assignments/池实况重新解析（旧 binding 可能正是失败原因），`model_ref`/`modelRef` 可显式指定；记录单向 `retriedFrom` 关系指向旧 Task，旧 Task 事实零变化，高级诊断以「重试来源」展示该关系。**Task 记录不持久化 Prompt**，生成指令必须由调用方重新提供（CLI `--input` / API `prompt` / 工作台弹窗重新输入），绝不从旧任务"恢复"——这是隐私设计，不是缺陷。同一请求网络重放的幂等键未实现：每次显式确认即一个新任务，属预期语义。
 
 ## 作品与只读诊断
 

package/docs/DSH_PROVIDER_CONNECTIONS.md

@@ -1,6 +1,6 @@
 # 复用 DSH 供应商连接
 
-版本要求：Iris 0.2.6；发布状态见 [README](../README.md)。0.2.5 不包含此入口。
+本文对应 Iris 0.2.7，功能从 0.2.6 起提供；发布状态见 [README](../README.md)。0.2.5 不包含此入口。
 
 DSH 已有兼容媒体服务时，可以在 Iris 工作台引用它的连接，避免再次填写和保存 Base URL/API Key。Iris 保留自己的模型、媒体协议与功能池；宿主连接提供当前地址和凭据。已有手动供应商配置继续使用。
 

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

@@ -0,0 +1,40 @@
+# 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 或配置。
+
+## 调用与归属
+
+```text
+apply(ctx) → createDshRuntime({ dataRoot, getHost })
+                  ├─ 工具、Action、工作台显式接收同一实例
+                  ├─ 有界 Core 任务观察器与启动接管
+                  └─ 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` 服务持有实例，注册的回调捕获各自所属实例。路由部分注册失败时立即回滚已注册项。
+
+同一实例的 Core 写操作共用 [Application Runtime](CORE_RUNTIME_CONTRACT.md#应用运行时装配) 的 FIFO，每项独立取得和释放 writer。reader 独立运行，只读取已提交事实；多个读取不构成整个根的一致快照。不同根可并行，同一物理根的竞争写者返回 busy，空闲插件不一直占锁。
+
+复合操作沿用既有 Command、Provider runner、Music 和维护逻辑，通过内部 `run(reader|writer, callback)` 在同一个操作范围执行；该入口不作为 package export、HTTP 转发或第三方 SDK。业务输入在进入队列前复制，Adapter、Browser 和连接解析函数则作为明确的运行端口保留，不尝试序列化。
+
+## 观察、取消与卸载
+
+Core 自动观察仍由 DSH 实例提供有界定时节拍，每次至多执行一次观察。配置连接在每拍重新解析，按原 Task 的供应商、模型与端点 binding 核对；密钥轮换可生效，端点或协议漂移会停止观察，不向新端点发送旧任务 ID，也不重新提交。
+
+启动接管是实例持有的后台操作，慢连接解析不阻塞插件完成装载。卸载同步拒绝新操作，停止定时器、传播取消，等待接管、轮询、已装配的工具/动作、工作台管理和附件投影完成，并等待 Core 释放。重复 `dispose()` 返回同一个过程；忽略取消的外部端口仍须返回后才能完成卸载。旧实例不能在连接解析返回后重新注册观察器，也不能停止新实例的观察器。
+
+排队取消不创建 Task；执行中取消保留已受理或未知的真实事实，不自动请求远端取消。附件展示失败或晚返回不会撤销已提交的 Core 成功结果。普通错误不阻塞后续队列；租约释放失败会停止实例，保留错误与现场，不报告关闭成功、不自动抢锁。
+
+legacy watcher 与 SSE 仍共享原有模块资源；原生装配只用“最近注册实例”标记阻止旧实例迟到释放时停止新资源，不以此宣称完整多 profile 隔离。可选 Core 服务桥启动失败会撤销已注册工具并断开握手；桥按当前所选插件业务注册工具，音频能力仍明确不支持。
+
+## 当前边界与验证入口
+
+本轮实例化的是 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`。
+- `node scripts/verify-headless-package.mjs --offline`：使用已有缓存检查仓库外、无 DSH 的 CLI 安装闭包。
+
+这些隔离检查不替代日常完整 DSH、真实付费 Provider、Android 浏览器交互或 Windows/macOS 验收。当前版本与后续范围见 [路线图](ROADMAP.md)。

package/docs/FUNCTION_MODEL_POOLS.md

@@ -1,6 +1,6 @@
 # 功能模型池与调用方式
 
-版本要求：Iris 0.2.6；发布状态见 [README](../README.md)。0.2.4/0.2.5 使用 [严格功能名单](FUNCTION_MODEL_ASSIGNMENTS.md)；升级不会自动启用自动池。
+本文对应 Iris 0.2.7，功能从 0.2.6 起提供；发布状态见 [README](../README.md)。0.2.4/0.2.5 使用 [严格功能名单](FUNCTION_MODEL_ASSIGNMENTS.md)；升级不会自动启用自动池。
 
 ## 配好一次即可使用
 

package/docs/HEADLESS_CLI.md

@@ -2,14 +2,22 @@
 
 `run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。0.2.6 可选择自动池、仅用所选模型或停用，旧名单和空配置不自动改变，见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
-本文面向 Iris 0.2.6，涵盖无 DSH 的本地处理、媒体生成、视觉分析、配置和任务管理。媒体结果保存为 Core Artifact，可在后续进程中检查、分析或导出；纯视觉不自动创建产物。Core 内部接口与 Artifact v0 尚未冻结为公共 SDK。
+本文面向 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.6` 后运行 `npx dsh-iris --help`。源码入口为 `node bin/dsh-iris.js ...`；本地tarball也可用于安装。
+需要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，当前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)。
 
 0.2.4新增 `artifact import --data-root /absolute/path/core --input '{"image_path":"/absolute/path/source.png"}'`，将本地图片保存为持久作品，不调用模型；详见 [图片导入](IMAGE_IMPORT.md)。npm0.2.3不包含此命令。
 
+0.2.7 开始让图片生成、导入、比较、作品查询/导出和单项任务查询共用 [内部应用运行时](CORE_RUNTIME_CONTRACT.md#应用运行时装配)，提供实例写队列、输入快照和操作级取消/释放。每个 CLI 调用仍是独立进程，队列不在进程之间共享；同时写同一数据根仍可能返回 busy。已有命令参数和 Task/Artifact 格式保持。
+
+0.2.7 另提供 [固定图片流程](IMAGE_FLOW.md)：先在新的专用根 `flow init`，再导入素材并执行 `flow create/continue/select/export`；`flow inspect/list` 只读。Run 私有保存创作输入，Task 新增可选流程绑定；原 Task/Artifact 记录和配置不自动迁移，旧版 writer 不得写该流程根。此功能随 npm 0.2.7 分发。
+
+0.2.7 的 `api serve --data-root /absolute/path/flow-core --token-file /absolute/private/new-session.token` 默认启动 [只读本地 API](LOCAL_API.md)：固定回环监听、独立会话鉴权，提供模型/流程查询和受控图片。Token 写入新的根外私有文件，stdout 不含 Token；GET/HEAD 不写 Core 或调用 Provider。新空 Flow 根可另执行 `api init`，再用 `--allow-local-writes` 主动启用 [上传/创建](LOCAL_CREATION.md)，它们不执行生成。执行/取消接口尚未开放；这些命令随 npm 0.2.7 分发；Demo 只保留在源码树中。
+
 ## 配置查询与离线诊断
 
 ```bash
@@ -24,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
@@ -187,7 +195,7 @@ dsh-iris task retry task_0123456789abcdef01234567 \
   [--model-ref providerId::modelId]
 ```
 
-缺 `--confirm-billing` 时在网络与创建之前拒绝。候选链按当前 assignments/池实况重新解析（不绑定旧 Provider/binding——旧配置可能正是失败原因），`--model-ref` 可显式指定。新 Task 有全新 id、attempts 与提交时实况 binding，并记录单向 `retriedFrom` 指向旧 Task；旧 Task 零变化。**Core 记录不持久化 Prompt**，所以生成指令必须由 `--input` 重新提供，绝不从旧任务恢复。DSH 侧同构开放：`POST /iris/api/core/task/:id/retry`（请求体必须 `confirmBilling:true`）与工作台「重试为新任务」按钮（重新输入指令 + 重复计费确认弹窗）。
+缺 `--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` 中。
 

package/docs/HOST_DOCTOR.md

@@ -5,7 +5,7 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 | 模式 | 入口 | 观察范围 |
 |---|---|---|
 | `offline` | `dsh-iris doctor [--json]` | Node、依赖、私有存储、配置、Task 与产物；不要求 DSH |
-| `host` | 运行中 DSH 的 `GET /iris/api/doctor` | DSH与Host Port、插件、当前工具/Skill、4组路由、Browser/附件/模型、客户端版本和4个UI Slot；Iris 0.2.6保留17工具/3项Skill |
+| `host` | 运行中 DSH 的 `GET /iris/api/doctor` | DSH与Host Port、插件、当前工具/Skill、4组路由、Browser/附件/模型、客户端版本和4个UI Slot；Iris 0.2.7保留17工具/3项DSH Skill |
 
 0.2.4新增 `iris_import_image`，图片导入自身不调用模型。0.2.3检查16工具/3项Skill，发布状态见 [README](../README.md)。
 
@@ -49,3 +49,15 @@ Iris0.2.5的Doctor与package顶层/嵌套DSH engines及客户端peer统一覆盖
 Host Adapter 将每项端口标记为 `available`、`unavailable` 或 `incompatible`，并给出同一份人类可读原因。工具注册与 Web 路由是 DSH 插件形态的硬要求；Skill、Browser、附件、会话以及宿主文本/视觉模型可按功能降级。
 
 客户端握手是当前浏览器实例的最后报告。关闭页面后报告不会立刻证明页面仍存活，因此它是装载兼容性证据，不是在线心跳。Host Doctor 也不替代真实 Provider 探针；任何可能计费的测试仍必须由用户显式触发。
+
+## 截图地址与主动自检（0.2.7）
+
+浏览器检查明确报告“接口已提供”，实际能否启动进程、打开渲染页面并截图，需要另做自检。服务端的 `clientSlots=unavailable` 不直接表示前端设置面板损坏，应看 `checks.client` 的握手和四个 Slot 登记事实。
+
+DSH Browser Port 附带只读的截图地址信息，Doctor 展示其来源：显式 `DSH_WEB_BASE` 优先，其次使用宿主公开的 host/实际 port/protocol；旧 HTTP 宿主没有 protocol 字段时保持 HTTP。`0.0.0.0` 和 `::` 分别转换为本机回环地址。没有可靠监听信息时显示 3080 回落提示，不把配置端口 0 当实际端口。无效显式地址会拒绝截图，不静默回落；报告不回显其中可能包含的凭据或 token。
+
+这里的地址仅用于浏览器导航，公开媒体播放链接保持原 `webBase()` 约定。反代路径前缀、HTTPS 证书信任和远程浏览器无法只凭监听地址推断；需要时显式设置其实际可访问的 `DSH_WEB_BASE`。地址解析不读取私有配置、请求 Host 或转发头，也不修改路由守卫、认证或浏览器写权限。
+
+“截图自检”由用户主动点击，复用现有 `POST /iris/api/actions/html`，提交固定的中文和内联样式样例，生成一张 Core 本地测试作品。界面显示本次结果和耗时；预览默认折叠，从现有受保护媒体路由读取作品。自检不读取个人会话、不加载外部资源、不调用模型。每次点击会新增测试作品，可以通过作品库已有管理功能处理。
+
+同一组件检测期间阻止重复提交，提供取消，最多等待 60 秒；关闭组件会中止请求，迟到结果不覆盖新一轮状态。取消/超时仅表示停止等待，若服务端恰好已经提交作品，仍可能在作品库看到结果。成功证据只属于本次检查，不持久标记为宿主永远健康。打开页面和点击“刷新”继续只读，不运行截图自检。