@mokuyoaxis/dsh-iris 0.2.6 → 0.2.7

package/docs/AGENT_QUICKSTART.md

@@ -2,16 +2,16 @@
 
 把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
 
-下列 npm 示例对应 Iris 0.2.6，准确范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。执行安装命令前确认所选发行包的实际版本、工具和功能策略。
+下列 npm 示例对应 Iris 0.2.7，准确范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。执行安装命令前确认所选发行包的实际版本、工具和功能策略。
 
 ## 中文
 
 ```text
 请根据本仓库 README，帮我安装并使用 Iris（@mokuyoaxis/dsh-iris）。
 先确认运行环境、目标 DSH profile，并用 dsh --version 核对宿主；Iris 0.2.x 要求 Node.js >=22.0.0（旧 npm 0.1.4 的历史要求为 >=20.10.0）：
-- DSH在docs/DSH_COMPATIBILITY.md列出的12个准确版本中：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6；只下载用 npm pack @mokuyoaxis/dsh-iris@0.2.6。
+- DSH在docs/DSH_COMPATIBILITY.md列出的12个准确版本中：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7；只下载用 npm pack @mokuyoaxis/dsh-iris@0.2.7。
 - 未列入所选Iris版本兼容矩阵的DSH：先报告没有支持声明，不自行升级宿主或跳过版本检查。
-没有DSH、希望用CLI时，按docs/HEADLESS_CLI.md使用npm0.2.6；npm0.1.4不含当前Core媒体CLI。
+没有DSH、希望用CLI时，按docs/HEADLESS_CLI.md使用npm0.2.7；npm0.1.4不含当前Core媒体CLI。
 先用--help和Doctor核对实际版本与命令。可引用DSH已有API Key连接，再确认模型用途并主动启用自动池，或保留手选名单；旧空配置不自动启用。DSH默认视觉须明确加入或启用。目录新增模型仍需确认用途；不以实测请求探测配置。图片导入用iris_import_image，改图用iris_edit_image；音乐用iris_generate_music并配置Chat Completions（内嵌音频）协议，见docs/MUSIC.md。
 从dsh-market安装也要核对实际包名、版本和兼容范围；缓存的旧版安装信息仍按其历史矩阵判断。
 若使用其他 profile，把示例中的 web 换成已确认的目标。保留完整 scoped 包名，不把 dsh-iris 当作同一 npm 包。
@@ -25,9 +25,9 @@
 ```text
 Help me install and use Iris (@mokuyoaxis/dsh-iris) according to this repository's README.
 Check the environment, target DSH profile, and dsh --version first; Iris 0.2.x requires Node.js >=22.0.0 (the published npm 0.1.4 historically requires >=20.10.0):
-- For one of the twelve exact DSH versions in docs/DSH_COMPATIBILITY.md, pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6; download only with npm pack @mokuyoaxis/dsh-iris@0.2.6.
+- For one of the twelve exact DSH versions in docs/DSH_COMPATIBILITY.md, pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7; download only with npm pack @mokuyoaxis/dsh-iris@0.2.7.
 - DSH versions outside the selected Iris version's matrix: report the missing support claim; do not upgrade the host or bypass its version checks automatically.
-For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm0.2.6; npm0.1.4 lacks the current Core media CLI.
+For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm0.2.7; npm0.1.4 lacks the current Core media CLI.
 Check --help, Doctor and the actual installed version. Reference a DSH API-key connection when available, confirm model uses, and explicitly enable automatic pools or retain selected-only lists. Existing empty configurations stay inactive. Host vision and new directory models require explicit authorization. Do not probe paid models to check configuration. Use iris_import_image for import, iris_edit_image for editing, and iris_generate_music with its configured inline-audio protocol for music.
 For dsh-market, check the actual package name, version, and compatibility range too. Cached older releases retain their historical compatibility matrices.
 Replace web with the confirmed profile when needed. Keep the scoped package name; unscoped dsh-iris is a different npm package.

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Iris 架构与边界
 
-状态：本文描述 **Iris0.2.5** 的架构。0.2.0建立实例化Core Runtime、Headless CLI及共享Task/Artifact事实；后续加入共享视觉、图片编辑、音乐和交付恢复。0.2.4补图片导入、原生Qwen改图和统一功能分配；0.2.5按接口能力恢复旧宿主支持。准确版本及历史发行范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。Node.js最低22.0.0；Core内部API尚未冻结为公共SDK。
+状态：本文描述 **Iris 0.2.7** 的架构。0.2.0 建立实例化 Core Runtime、Headless CLI 及共享 Task/Artifact 事实；后续加入共享视觉、图片编辑、音乐和交付恢复。0.2.5 恢复旧宿主支持，0.2.6 增加连接引用、可选功能自动池和目录同步。准确版本及历史发行范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。Node.js 最低 22.0.0；Core 内部 API 尚未冻结为公共 SDK。
 
 ## 当前形态
 
@@ -33,7 +33,9 @@ DSH Host / Cordis                         Headless CLI
                     CLI: explicit absolute data root
 ```
 
-`lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 只负责选择 DSH profile 的 Core 数据根、恢复 Provider 配置和投影 Host DTO。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
+`lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 负责 DSH 的 Core 实例装配、Provider 连接解析和 Host DTO 投影。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
+
+0.2.7 增加 `lib/application-runtime.js`，首批 CLI 图片命令和固定改图流程通过它装配 Core；[DSH 实例](DSH_RUNTIME.md)也已接入同一队列机制。写队列、操作取消和关闭归属于应用实例；每次写操作独立取得、释放 Core 租约，DSH 的 Core 观察器由插件实例持有并等待卸载。[固定流程](IMAGE_FLOW.md)使用专用根中的版本化 Run、稳定 Task/比较作品身份及引用保护，私有输入保存提示词，Task 仅保存可选流程绑定。[本地 API](LOCAL_API.md)已提供默认只读与主动启用的 [本地创建](LOCAL_CREATION.md)，执行/取消、通用 Recipe 和真实独立 Web 仍待完成。详见 [应用运行时契约](CORE_RUNTIME_CONTRACT.md#应用运行时装配)。上图表示已发布入口的共同核心。
 
 0.2.1的 S2V 使用 Core Task/Attempt，HTML 使用 `media.html` 与显式 Browser Port；视觉和提示词预览通过共享 Model Ports 执行。纯视觉不创建 Task/Artifact，摘要主动转写仍使用 Core 任务。聊天改图属于媒体生成链，按来源 Artifact ID 创建新 Task 和关联产物。
 
@@ -42,6 +44,8 @@ DSH Host / Cordis                         Headless CLI
 | 模块 | 职责 | DSH 运行时依赖 |
 |---|---|---:|
 | `core-contract.js` / `core-runtime.js` / `core-writer-lease.js`（0.2.2） | 显式数据根、reader/writer 权限、单写者租约、取消与释放 | 无 |
+| `application-runtime.js` | 实例写队列、操作输入快照与 Core 装配；首批由 CLI 消费 | 无 |
+| `flow-store.js` / `image-flow.js` | 专用根、私有 Run 输入、固定步骤绑定、原任务恢复与用户选择 | 无 |
 | `command-service.js` | 本地媒体命令、Task 控制面和 Artifact 查询/导出 | 无 |
 | `generation-input.js` | CLI、DSH 与重试共用的生成参数校验和 Provider 字段转换 | 无 |
 | `model-port-contract.js` / `model-invoker.js` | Text/Vision 内部契约、有限调用预算与取消 | 无 |
@@ -74,7 +78,9 @@ DSH Host / Cordis                         Headless CLI
 
 ## Provider 边界
 
-0.2.4将六类功能统一为严格有序分配名单：不补入全局池，临时指定只绑定名单内单项。DSH默认视觉为显式宿主资源，不作为隐式兜底；手动实测与旧任务恢复保持独立。配置格式、Core受理纪律与生产依赖保持。升级范围见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。下方0.2.2描述保留当时能力声明变更的背景。
+0.2.6 的六类功能可选择自动池、仅用所选模型或停用。自动池只从已确认用途的模型中按稳定顺序选择，不授权目录新条目，也没有跨请求轮转；旧名单和缺失/空分配不自动启用。DSH 默认视觉仍需明确加入允许范围，手动实测与旧任务恢复保持独立。连接引用由 DSH Adapter 在操作期间解析，Core 不接收宿主凭据引用。详见 [功能模型池](FUNCTION_MODEL_POOLS.md)与 [连接复用](DSH_PROVIDER_CONNECTIONS.md)。
+
+0.2.4/0.2.5 的严格有序名单规则见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。下方 0.2.2 描述保留当时能力声明变更的背景。
 
 0.2.2按功能组织有序模型候选池，能力来自明确模型标签、旧能力字段绑定或供应商能力元数据。裸账号不物化默认模型，模型名称不授权进入候选链；明确空池与空标签保持权威。模型与供应商复合身份用于底层执行器，功能入口、分配排序及安全 failover 没有改为模型中心产品或默认轮转。旧 0.2.1 的能力推断行为不再用于裸账号或模型名称赋能。
 

package/docs/CLI_MANAGEMENT.md

@@ -1,6 +1,6 @@
 # CLI 配置与任务管理
 
-本文面向 Iris 0.2.6，沿用 `dsh-iris` 入口，无需启动 DSH。安装 `npm install @mokuyoaxis/dsh-iris@0.2.6` 后运行 `npx dsh-iris ...`；也可从源码或本地 tarball 使用同一入口。发布状态见 [README](../README.md)；视觉命令见 [视觉 CLI](VISION_CLI.md)，基础媒体链路见 [Headless CLI](HEADLESS_CLI.md)。
+本文面向 Iris 0.2.7，沿用 `dsh-iris` 入口，无需启动 DSH。安装 `npm install @mokuyoaxis/dsh-iris@0.2.7` 后运行 `npx dsh-iris ...`；也可从源码或本地 tarball 使用同一入口。发布状态见 [README](../README.md)；视觉命令见 [视觉 CLI](VISION_CLI.md)，基础媒体链路见 [Headless CLI](HEADLESS_CLI.md)。
 
 所有需要 JSON 的命令均支持 `--input '<json>'`、`--input-file /path/input.json` 或 `--input -`（stdin），只能选择一种，输入最多 2 MiB。私有配置必须是普通文件、绝对路径，POSIX 权限为 `0600`。真实请求只由显式执行生成、发现、实测或观察命令触发。
 

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` 也尚未迁移。
 
 ## 目标与范围
 
@@ -72,6 +72,37 @@ 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`，旧记录不批量改写。已有 Attempt 后继续操作只核对原事实、观察或补交付，不重新 submit；完整异步 Flow 结果也先缓存，再按原 Artifact ID 交付。原图和流程作品/Task 同步纳入删除保护。通用 Recipe、API 执行/取消和 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 保持。
+
+默认只读路径不取得 writer；显式本地写路径按操作取得 writer，只有配置解析 descriptor，没有生成/观察 Adapter。上传和创建都是本地提交，继续/选择/Operation/取消 API 仍待后续。旧 binary 没有请求区检查，新专用根只支持已验收的 request-aware writer；不宣称旧程序看到标记就会拒写，也不承诺断电跨文件事务。
+
+作品存储新增内部 `inspectCoreArtifactMetadata`，用于在读取大文件前验证清单与普通文件大小；该元数据入口不核验完整字节哈希，不能单独据此向外提供媒体。HTTP Host 在限额内继续使用 `readCoreArtifactBytes` 并复核已取字节的摘要，才返回图片。既有作品读取、持久化格式与内容哈希要求保持。
+
 ## 当前接口与后续范围
 
 0.2.3 增加同步完成结果的私有交付缓存：`task.redeliver` 可从原结果恢复，无需虚构远端 ID；完整字节离线交付，缺失字节只取回原 URL，不 submit。完整缓存可补回提交完成事实的中断，预留 Artifact ID 支持逐件重入；缓存与任务隔离/恢复一起管理。详见 [同步交付恢复](SYNC_DELIVERY_RECOVERY.md)。
@@ -80,7 +111,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 +119,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_SKILLS.md

@@ -0,0 +1,62 @@
+# 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` 界面元数据。参考链接均位于该目录内，分发时保留整个目录。
+
+使用支持 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。
+
+## 当前边界
+
+- 首版覆盖图片及其任务，支持单步操作和图片续作；视频、语音和界面验收不在首版范围内。
+- DSH 原有三项 Skill、工具、附件与工作台流程保持，不把新 Skill 自动注册为第四项 DSH Skill；DSH 使用方式见 [README](../README.md#agent-skills)。
+- 本版新增独立的 Core 指导，不迁移或改写旧 DSH Skill。后续若合并公共参考，应先证明 DSH 流程和资源解析保持。
+- Core Artifact ID 属于指定根，宿主附件、路径与 URL 不可互换；交付时由实际宿主呈现导出文件。
+- 正式 MCP 仍待实现。当前 Skill 的可执行说明只有 CLI，不能用它声称 MCP 已安装或第二生产 Host 已完成。
+- 面向 Core 的独立工作台继续按既有路线推进；本 Skill 不描述尚不存在的 UI 操作。Skill 指导 Agent，业务受理、写者租约与重试约束继续由执行层负责。
+
+验收区分 Skill 文件/引用可读取、CLI 示例可执行、实际 Agent 是否按指导完成任务。离线供应商夹具只验证命令和状态处理，不证明真实模型的规划、生图质量或计费表现。

package/docs/DSH_COMPATIBILITY.md

@@ -2,9 +2,9 @@
 
 Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安装的Iris版本；发布状态见 [README](../README.md)。
 
-## Iris 0.2.6
+## Iris 0.2.7
 
-0.2.6 沿用 0.2.5 的以下 12 个准确版本声明，不因连接复用扩大宿主支持范围。连接引用另需供应商目录、脱敏设置及凭据公开服务；缺少接口时使用手动供应商。首次配置与升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
+0.2.7 沿用 0.2.5/0.2.6 的以下 12 个准确版本声明。截图修复与实例装配不扩大宿主支持范围。连接引用另需供应商目录、脱敏设置及凭据公开服务；缺少接口时使用手动供应商。首次配置与升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
 ## 0.2.5 建立的兼容范围
 
@@ -34,10 +34,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_RUNTIME.md

@@ -0,0 +1,36 @@
+# DSH 实例运行时（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 成功结果。普通错误不阻塞后续队列；租约释放失败会停止实例，保留错误与现场，不报告关闭成功、不自动抢锁。
+
+## 当前边界与验证入口
+
+本轮实例化的是 DSH 的 Core 装配及上述操作。legacy `config.js`、`tasks.js`、`artifacts.js`、上传与 SSE 存储/资源仍保留原机制，不承诺同进程多个 profile 的完整隔离；其他 CLI 入口也未全部统一。固定 Flow 尚未接入 DSH 工作台，本地 API 的 Operation、执行/取消和真实 Web 联调另行推进。公开 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 仍待实现。
 
 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
@@ -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 秒；关闭组件会中止请求，迟到结果不覆盖新一轮状态。取消/超时仅表示停止等待，若服务端恰好已经提交作品，仍可能在作品库看到结果。成功证据只属于本次检查，不持久标记为宿主永远健康。打开页面和点击“刷新”继续只读，不运行截图自检。

package/docs/IMAGE_FLOW.md

@@ -0,0 +1,71 @@
+# 固定图片流程（0.2.7）
+
+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 的导出路径暴露给浏览器。
+
+## 初始化与创建
+
+先选择一个新的、空的专用 Core 数据根。`flow init` 不迁移现有 DSH/CLI 数据根；初始化后才向它导入图片。已有有效流程根上再次执行 init 不改变声明。
+
+```bash
+dsh-iris flow init --data-root /absolute/path/flow-core
+dsh-iris artifact import --data-root /absolute/path/flow-core --input '{"image_path":"/absolute/path/source.png"}'
+```
+
+使用返回的 Artifact ID 编写输入文件，例如：
+
+```json
+{
+  "source_artifact_id": "artifact_<返回的24位十六进制ID>",
+  "model_ref": "providerId::modelId",
+  "prompt": "将背景改成绿色，保留主体",
+  "n": 1
+}
+```
+
+替换示例中的 ID 与模型，保存为 `/absolute/path/edit.json`，再创建流程：
+
+```bash
+dsh-iris flow create --data-root /absolute/path/flow-core --provider-config /absolute/path/providers.json --input-file /absolute/path/edit.json
+dsh-iris flow list --data-root /absolute/path/flow-core
+```
+
+create 只验证原图、模型允许范围与改图协议，保存输入和预留身份，**不提交生成请求**。首版要求明确模型、单张结果 `n=1`，可选 `size`；支持现有聊天图片和原生 Qwen 改图协议。Provider 配置仍按 [功能池](FUNCTION_MODEL_POOLS.md)和 [CLI 配置](HEADLESS_CLI.md)处理。
+
+## 执行、选择与导出
+
+将下方引号内的占位 ID 替换为 create 返回的 Run ID。首次 continue 可能调用指定模型并产生费用：
+
+```bash
+dsh-iris flow continue 'run_<24hex>' --data-root /absolute/path/flow-core --provider-config /absolute/path/providers.json
+dsh-iris flow inspect 'run_<24hex>' --data-root /absolute/path/flow-core
+dsh-iris flow select 'run_<24hex>' --data-root /absolute/path/flow-core --input '{"artifact_id":"artifact_<原图或新版ID>"}'
+dsh-iris flow export 'run_<24hex>' --data-root /absolute/path/flow-core --output /absolute/path/selected.png
+```
+
+continue 对同一 Run 复用预留 Task；已有 Attempt 后不重新 submit，也不按新模型池顺序改绑。已受理任务每次至多观察一次，生成成功但交付中断时恢复原缓存或原远端任务。完成结果不需要 Provider 配置即可继续、查看、选择和导出。连接端点/协议漂移、输入摘要不符或作品缺失会拒绝相应操作；API Key 轮换遵守原 Task 配置规则。
+
+| `status` | 含义 |
+|---|---|
+| `not_started` | 尚未提交；再次 continue 可执行首次生成 |
+| `running` | 原任务仍在执行，后续 continue 仅观察原任务 |
+| `needs_attention` | 未知受理、失败、取消或缺少可靠完成事实；不会自动重提 |
+| `delivery_failed` | 生成已成功，本地交付尚未完成 |
+| `needs_comparison` | 原 Task 已交付，流程的本地比较尚未完成 |
+| `awaiting_selection` | 改图和比较完成，等待明确选择 |
+| `selected` | 已选择原图或新版，尚不代表已导出 |
+
+像素比较只描述差异，不证明修改符合创作要求。选择仅接受本流程的原图或新版；重复选择相同作品不改记录。导出路径只用于当次调用，不写入 Run，不自动恢复外部路径写入，也不覆盖现有文件。需要重新生成时应明确新建 Run，原 Run 不自动采用 `task retry` 创建的新任务。
+
+## 持久化与恢复
+
+流程根使用 `flow-store/v0/root.json` 声明，Run 保存在 `flow-store/v0/runs/`。它保存版本、源图 SHA256、创作输入、模型/连接绑定摘要、预留 Task/比较作品 ID、交付引用和选择。**提示词是私有 Run 输入**，`flow inspect` 会返回它，list 只返回摘要；Task 继续不保存提示词、Key、端点或宿主路径。POSIX 下目录/文件沿用 0700/0600；Windows 文件 mode 不等于 ACL。
+
+Task 仍使用 schemaVersion 0 / semanticsVersion 2，新增可选 `flowBinding` 记录 Run、步骤和输入摘要。旧 Task 无需改写。步骤意图先落盘，Task 排他建立后再记录检查点，Attempt 必须先于 Provider 调用。已有 Attempt 但没有可靠响应时，即使 `acceptance=none`，也不能推断请求尚未发送。完整缓存可以接回原结果；缺少证据时保留未知。
+
+比较图使用预留 ID、时间和内容证据重入；不会因 Run 完成标记未写入就另建随机比较作品。进程异常留下的写者租约仍按 [显式恢复流程](HEADLESS_CLI.md#异常退出后的写者租约)处理，不抢锁或手动删除租约。
+
+Run 引用的原图、结果、比较作品和 Task 均进入现有删除/清理保护；Run 或绑定损坏时管理操作停止。首版不提供 Run 删除、自动 GC 或完整通用 Recipe 编辑器。流程根**不能与旧版 writer 混用或降级写入**：旧版能读 Task 不代表其清理器认识 Run 引用；回退使用原有数据根或只读导出。
+
+当前恢复证据来自隔离根中的进程强杀、受控 Provider 与本地 HTTP。它不保证真实 Provider 的通用 exactly-once、断电持久性、网络/Android 共享文件系统支持或所有平台的实际运行；基础目录应放在支持现有 writer 租约的私有文件系统中。

package/docs/LOCAL_API.md

@@ -0,0 +1,60 @@
+# 只读本地 API（0.2.7 / I4A）
+
+0.2.7 增加显式启动的本地 HTTP 入口，默认只提供 GET/HEAD，用来验证无 DSH 环境下的流程查询与图片访问。另有主动启用的 [本地上传与创建](LOCAL_CREATION.md)；继续、选择和取消等执行接口尚未开放。安装包不会自动启动本服务。
+
+现有 [Web Demo](WEB_PROTOTYPE.md)继续保留为面向 0.3.0 的交互说明，尚未连接这个 API；界面和交互细节到 0.3.0 阶段统一润色。[完整 API 契约](LOCAL_API_CONTRACT.md)中的执行与 Operation 部分仍是设计稿。
+
+## 显式启动与停止
+
+准备一个已经由 `flow init` 初始化的专用根，操作见 [固定图片流程](IMAGE_FLOW.md)。只读服务不会创建缺失的根或转换旧根。
+
+```bash
+dsh-iris api serve --data-root /absolute/path/flow-core --token-file /absolute/private/iris-session-001.token
+```
+
+`token-file` 必须是**新文件的绝对路径**，已有父目录须可写，且该文件位于 Core 根之外。启动时生成新的随机 Token，写入此文件；POSIX 文件权限为 0600。终端只打印服务地址、文件路径和只读说明，不打印 Token；URL 与接口响应也不带 Token。请使用支持私有文件权限的本地目录；Windows 的 mode 不等于 ACL，权限依赖系统账户控制。
+
+服务固定监听 `127.0.0.1`，默认随机端口；可用 `--port 4174` 指定端口，占用时报错。打印的 JSON 中 `origin` 是本次服务地址。`--provider-config /absolute/path/providers.json` 可选：提供时，模型列表只读解析该显式文件，不发现/同步模型、不调用 Provider、不返回 Key 或端点；省略时仍可离线查看流程和已保存图片，模型列表返回 `configured: false`。
+
+Ctrl+C 关闭监听和连接，等待读取释放；POSIX 下也支持 SIGTERM。Windows 的进程终止信号行为不同，其优雅停机尚未实际验证。停机后本次 Token 失效；重启使用新的 Token 文件名。旧 Token 文件保留，不覆盖或自动清理，不作为下次启动凭据。启动和关闭均不持有 Core writer，不重启 DSH。
+
+## 身份与访问
+
+每个接口都要求 `Authorization: Bearer <Token>`。Token 从私有文件读取，保持在调用进程内存中，不放进 URL、命令行参数、聊天或共享日志。下面仅把文件路径交给 Node，示例响应不包含 Token；替换实际端口与文件路径后执行：
+
+```bash
+node --input-type=module - http://127.0.0.1:4174 /absolute/private/iris-session-001.token <<'JS'
+import fs from 'node:fs';
+const [origin, tokenFile] = process.argv.slice(2);
+const token = fs.readFileSync(tokenFile, 'utf8').trim();
+const response = await fetch(new URL('/api/v0/session', origin), {
+  headers: { Authorization: 'Bearer ' + token }
+});
+console.log(response.status, await response.json());
+JS
+```
+
+Host 必须精确匹配启动地址；带 Origin 时须等于该 origin，跨源、`null` 来源和跨站请求拒绝，不采信转发头，不开放 CORS。所有响应禁止缓存并使用 nosniff；未认证时返回 401，不读取流程或模型配置。Token 文件或浏览器已有 DSH 登录状态不能代替本 API 的 Bearer 请求头。
+
+## 当前接口
+
+以下路径都以 `/api/v0` 开头，支持 GET 和 HEAD；HEAD 完成同样的鉴权与校验，响应无正文。
+
+| 路径 | 结果 |
+|---|---|
+| `/session` | 实例标识、只读能力和限额，无根路径或 Token |
+| `/models` | 当前图片候选的模型引用、显示名、`supportsImageEdit`；只是配置事实，不是实测可用性 |
+| `/runs?limit=20&cursor=…` | 最多 30 项摘要，不含 Prompt；`nextCursor` 是下一页使用的最后 Run ID，末页为 null |
+| `/runs/:id` | 白名单 FlowView，含用户创作输入和原 Task 的有限事实；未知状态保持，不自动恢复 |
+| `/artifacts/:id/content` | 已提交图片的原字节，按 ID 读取该根中的作品，不接受本地路径或外部 URL |
+| `/runs/:id/download` | 已选择作品的原字节与固定附件名；尚未选择返回 409，不写服务器输出路径 |
+
+图片访问仅提供 PNG、JPEG、WebP，单份最多 64 MiB；当前使用有界、已核验内容哈希的字节快照。大型媒体的磁盘流式、Range 和音视频访问留到后续，不作为本切片能力。最多两个活动读取，繁忙返回 429。列表使用现有 Flow 存储逐项盘点，页数限制只约束响应数量，尚未建立大型目录索引。
+
+默认只读模式下，非 GET/HEAD 方法返回 405；不支持的路径返回 404，未知/重复查询参数或格式错误的 ID 返回 400。损坏/不一致的记录返回 409，不修复原文件；错误只包含固定代码、说明和关联 ID，不透传堆栈、配置、私有路径或 Provider 错误原文。
+
+详情和图片属于私有创作数据，均需鉴权。列表、查看、HEAD、刷新与下载不会调用 `flow.continue`，不会补交付或重新生成；下载请求成功也不证明浏览器已保存文件。CLI 的本地 `flow export` 仍是单独的显式写操作。
+
+## 后续范围
+
+默认入口保持 I4A 的只读行为。0.2.7 的 [I4B](LOCAL_CREATION.md)另提供新空根请求区与 `--allow-local-writes`：上传和 Run 创建使用持久 Key/预留身份，本地提交后 201、重放 200；不执行生成。有限执行/取消和真实 Web 联调留到后续，不改 Flow/Task/Artifact 格式、不迁移原数据根或冻结公共 SDK。