@mokuyoaxis/dsh-iris 0.2.5 → 0.2.7

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,7 +2,11 @@
 
 Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安装的Iris版本；发布状态见 [README](../README.md)。
 
-## Iris 0.2.5
+## Iris 0.2.7
+
+0.2.7 沿用 0.2.5/0.2.6 的以下 12 个准确版本声明。截图修复与实例装配不扩大宿主支持范围。连接引用另需供应商目录、脱敏设置及凭据公开服务；缺少接口时使用手动供应商。首次配置与升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
+
+## 0.2.5 建立的兼容范围
 
 0.2.5恢复旧宿主支持，并覆盖以下12个准确版本。旧宿主使用同一套 Iris Core、Music、图片导入和原生 Qwen 改图功能，无需维护旧版功能分支。
 
@@ -30,15 +34,15 @@ Iris与DSH的版本号独立。安装前运行 `dsh --version`，并核对要安
 
 ## 安装与升级
 
-在上述12个准确版本的宿主中固定安装0.2.5：
+在上述 12 个准确版本的宿主中，固定安装 Iris 0.2.7：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.5
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7
 ```
 
 使用其他profile时替换 `web`。更新后检查服务端装载、刷新Web客户端，并查看Iris工作台的 [宿主诊断](HOST_DOCTOR.md)。alpha.3及之后的DSH改善了插件更新与热加载，但仍以实际装载结果为准。
 
-0.2.4起统一六类功能的明确模型名单。已有分配保持；以前依赖自动模型池的功能需要在升级后明确分配，见 [升级说明](FUNCTION_MODEL_ASSIGNMENTS.md)。本次宿主适配不迁移旧作品、任务或个人配置；从Iris0.1.4整体升级的旧数据流程仍需单独验收。
+0.2.4/0.2.5 统一六类功能的明确模型名单；0.2.6 可主动启用自动池，旧名单和空配置不自动改变，见 [功能池及升级说明](FUNCTION_MODEL_POOLS.md)。从 Iris 0.1.4 整体升级的旧数据流程仍需单独验收。
 
 ## 兼容声明如何生效
 

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

@@ -0,0 +1,34 @@
+# 复用 DSH 供应商连接
+
+本文对应 Iris 0.2.7，功能从 0.2.6 起提供；发布状态见 [README](../README.md)。0.2.5 不包含此入口。
+
+DSH 已有兼容媒体服务时，可以在 Iris 工作台引用它的连接，避免再次填写和保存 Base URL/API Key。Iris 保留自己的模型、媒体协议与功能池；宿主连接提供当前地址和凭据。已有手动供应商配置继续使用。
+
+## 工作台操作
+
+1. 打开“添加供应商”，在“连接来源”选择已配置的 DSH 连接。
+2. 明确选择该服务实际支持的媒体协议，保存。
+3. 发现或添加媒体模型，确认它用于哪些功能。首次配置可同时启用所选功能的自动池，保存即可使用，无需再次逐项分配。
+
+引用连接不会自动发现、实测或生成；只有用户确认的用途和功能策略决定调用范围。已有手工名单或停用状态不会自动改变。DSH 能进行文字对话不证明相同服务支持媒体接口；协议、账号权限和模型能力仍需核对。三种调用方式见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
+
+## 地址、密钥与恢复
+
+Iris 配置只保存 `dshProvider: { provider, settingsNs }`，不保存该连接的普通 Base URL 或密钥。操作期间，DSH 适配层通过公开供应商目录、已脱敏设置描述和凭据接口构造内存副本；不同并发操作的副本隔离，不进入配置持久化。
+
+DSH 的地址或密钥变化影响下一次操作。Iris 供应商列表展示连接来源、地址和可用状态，密钥只显示“由 DSH 管理”。停止使用引用或删除 Iris 供应商不会修改 DSH 原连接。
+
+离线 Doctor 不解析宿主引用，会提示“需由运行中宿主解析”，不会要求再填写同一把密钥。请在 DSH 工作台查看连接状态和功能池候选；候选元数据不代替真实接口权限验证。
+
+原连接停用、移除或无法解析时，该项不可用；显式指定该模型不会换用其他账号。原任务的恢复继续校验提交端点和协议绑定，地址改变时拒绝向新端点观察原任务，不会重新生成。已缓存完整字节的本地补交付沿用现有规则。
+
+## 支持范围
+
+- 需要 DSH 的 `llm.listProviders/listConfigurableProviders`、`settings.describe` 和对应凭据服务。
+- 支持配置中的 `apiKeyEnv` 引用、默认 `llm-pi-ai` 实例的 API Key 记录，以及目录明确声明的环境凭据引用。
+- OAuth/登录授权、专有签名和自定义请求头不转换为媒体认证；界面显示原因，可继续手动添加适合的媒体供应商。
+- 尚不自动处理别名 `llm-pi-ai` 实例的私有记录归属；这类实例可以使用公开的 `apiKeyEnv` 引用。
+- 缺少接口的旧宿主保留手动配置。连接复用能力按实际服务检测，不扩大已有宿主版本声明。
+- Headless CLI 不读取 DSH 连接。CLI 媒体调用继续使用显式的独立 Provider 配置；含 DSH 引用的条目不能在无宿主进程中解析。
+
+此功能不迁移已有配置、导出宿主密钥或读取其他项目文件；功能策略由用户明确选择，受理后不自动重提和单写者约束继续保留。

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_ASSIGNMENTS.md

@@ -2,6 +2,8 @@
 
 版本要求：Iris0.2.4。0.2.3只有Music采用严格名单；本页说明升级后的统一规则，发布状态见 [README](../README.md)。
 
+本页说明 0.2.4/0.2.5 的规则，以及 0.2.6 中“仅用所选模型”的行为。0.2.6 另提供 [自动池、手选与停用](FUNCTION_MODEL_POOLS.md)；旧名单及缺失/空分配继续保持本页行为，不会静默启用自动池。以下“只有名单内模型参与”仅适用于手选模式。
+
 在“功能分配（调用顺序）”中为图片、视频、语音、音乐、转写和视觉分别选择模型。模型池登记资源、能力、协议和健康；只有加入功能名单的模型参与该功能的新请求。普通模型使用 `providerId::modelId` 复合引用，同名模型的不同账号独立选择。
 
 每次请求按名单顺序选择。已停用、缺少配置、已知冷却或不支持本次模式的项可跳过；名单之外的模型不会补入。临时指定模型也必须属于名单，且本次只调用指定项；失败不会改用其他模型。没有分配或名单全部不可用时明确失败。

package/docs/FUNCTION_MODEL_POOLS.md

@@ -0,0 +1,84 @@
+# 功能模型池与调用方式
+
+本文对应 Iris 0.2.7，功能从 0.2.6 起提供；发布状态见 [README](../README.md)。0.2.4/0.2.5 使用 [严格功能名单](FUNCTION_MODEL_ASSIGNMENTS.md)；升级不会自动启用自动池。
+
+## 配好一次即可使用
+
+在工作台添加媒体供应商，或 [引用 DSH 已有连接](DSH_PROVIDER_CONNECTIONS.md)，选择实际支持的媒体协议。在供应商详情填写模型名，勾选它可用于哪些功能，点击“保存模型用途”。
+
+首次配置会推荐勾选“同时启用所选功能的自动池”。保存后，已确认的模型直接进入这些功能的候选，不需要再逐项添加到功能名单。已有配置不会自动改为此模式；启用框会明确说明它会替换所选功能的调用方式。仅保存用途不发起实测或生成，也不代表上游已验证可用。
+
+供应商详情的“模型目录”默认折叠，点击“同步目录”读取最新列表；发现的新条目显示“待确认用途”，确认后才会加入自动池。名称和 DSH 文字连接不证明媒体能力。Music 还需明确绑定 `musicProtocol: gemini-web-music`。
+
+## 目录更新与候选可用性
+
+新自动请求开始前按需检查供应商目录，成功结果缓存 10 分钟，同连接并发读取合并；也可在工作台主动同步。同步只读取目录，不发起模型实测或生成。配置检查、手选请求、停用功能与旧任务查询不会暗中刷新目录。同步失败保留上次完整目录及错误原因，短暂退避 30 秒；坏响应或不完整分页不会覆盖快照。
+
+目录展示同步时间、新条目与“目录未列出”的已配置模型。未列出本身不能证明下线：手工模型、用途和顺序继续保留，新模型仍需确认。混合视频/音频输出不自动获得 TTS 用途，音频理解也不自动获得文件转写用途；可信的明确能力代码优先。
+
+当当前连接在新提交或实测中明确返回模型不存在（模型专属错误码，或精确的 `404 Model not exist.`）时，仅隔离该连接的模型及能力，后续请求跳过它。通用路径 404、参数 400、认证错误、限流与网络错误不按模型消失处理。历史成功保留，可用性单独显示；目录重新列出不自动解除隔离。改变连接或有效图片协议后重新判断，也可在核对目录后单独确认费用进行实测，成功恢复。旧任务的查询、观察与交付仍沿用原绑定，不解除或新增此类阻断。
+
+DSH、Agent 和独立 CLI 共用规则。媒体的候选切换仍遵守受理边界；视觉保留已有操作停止规则，本次已发出的明确模型 404 会隔离后续请求，不因此扩张同一操作的切换条件。当前没有后台定时器、自动付费探针、按目录自动删除模型或自动授权新模型。
+
+## 每个功能有三种调用方式
+
+| 方式 | 候选范围 | 没有合格候选时 |
+|---|---|---|
+| 自动池 | 已确认用途、连接启用且协议支持的同功能模型，按供应商和模型登记顺序选择 | 显示候选为零及配置缺口，不发起请求 |
+| 仅用所选模型 | 只使用手选的有序名单，不补入其他模型 | 提示添加所选模型或切换模式 |
+| 停用 | 停止此功能的新调用 | 显式传入模型也不能绕过 |
+
+工作台“功能池与调用方式”展示各功能的候选数，以及未连接、待确认用途、协议不支持或限流等原因。切换自动池先展示影响并确认；切回手选会保留原名单。自动池不是网络连通或上游能力实测的保证。
+
+自动池采用页面内确认，确认前显示“尚未保存”；提交后在该功能旁依次显示“正在保存”“正在更新候选”和“已保存”。保存期间暂时禁用重复切换。若未收到确认，点击“刷新状态”只读取保存结果，不会再次提交；已保存但候选更新失败会分别说明。
+
+更新后，需让 DSH 服务端加载新代码，再刷新页面。仅刷新页面可能形成新界面配旧服务端；此时页面会提示重启 DSH，并暂停策略切换，避免把旧接口的成功响应误认为自动池已启用。
+
+生图和改图共享图片池，视频和 S2V 共享视频池，再按具体输入和协议过滤。看图、OCR、定位和视觉摘要共享视觉池。TTS、Music、转写分别使用自己的池；裁剪、导入、抽帧等本地操作不要求模型。
+
+自动视觉默认不包含宿主资源；需要时明确勾选“使用 DSH 当前视觉模型”。它仍须由宿主声明支持图片输入，独立 CLI 不能执行该资源。
+
+## 顺序选择与安全切换
+
+每个新请求从首个合格候选开始。A 明确未受理时可以继续 B；已知冷却项会跳过。此阶段没有跨请求 A→B→C 的轮转游标。
+
+临时指定模型须在当前允许范围内，本次只调用它，失败不替换。工作台默认保留自动选择，不会把首个候选填成显式参数；Agent 也只应在用户明确指定时传模型参数。
+
+媒体受理未知、已经受理或交付失败时，仍绑定原任务处理，不因池内还有模型就重新生成。池和策略变化只影响新请求，旧任务沿原模型、协议和端点绑定观察或补交付。Music 原有显式 502 重发规则独立保留，每次建立关联新任务，可能增加费用。
+
+## 旧配置与 CLI
+
+旧字符串、数组及对象形式的分配继续按原手选名单解释，缺失或空分配保持零调用；读取不会自动启用或迁移。用户主动切换策略时，旧引用归一化保存，原手工名单保留。无宿主 CLI 仍使用显式私有配置，不解析 DSH 连接引用。
+
+新策略在现有 `assignments` 中按功能保存，例如：
+
+```json
+{
+  "assignments": {
+    "image-gen": {"mode": "auto", "models": ["account::preferred-image"]},
+    "music-gen": {"mode": "manual", "models": ["account::music"]},
+    "vision": {"mode": "auto", "models": [], "hostVision": false},
+    "video-gen": {"mode": "disabled", "models": []}
+  }
+}
+```
+
+`models` 是保留的手工名单，自动模式不以它限制候选。新增模型必须有明确功能标签，发现条目须经用户确认；模型的限流、协议及实际输入约束继续生效。
+
+通过现有 CLI JSON 输入管理，无需增加命令或直接编辑配置：
+
+```bash
+dsh-iris models add 'account::image-a' --provider-config /absolute/path/providers.json \
+  --input '{"capabilities":["image-gen"],"enableAutomatic":true}'
+dsh-iris models caps 'account::image-b' --provider-config /absolute/path/providers.json \
+  --input '{"capabilities":["image-gen"]}'
+dsh-iris assignments set --provider-config /absolute/path/providers.json \
+  --input '{"capability":"image-gen","mode":"auto"}'
+dsh-iris assignments set --provider-config /absolute/path/providers.json \
+  --input '{"capability":"image-gen","mode":"manual","model_refs":["account::image-b"]}'
+dsh-iris assignments set --provider-config /absolute/path/providers.json \
+  --input '{"capability":"image-gen","mode":"disabled"}'
+dsh-iris capabilities list --provider-config /absolute/path/providers.json
+```
+
+`enableAutomatic:true` 是明确修改所选功能策略的动作；省略时只确认用途，已有自动功能会纳入该模型，已有手工/停用功能不变。`assignments clear` 继续清除该功能分配并停止新调用，不表示恢复自动。配置写入沿用唯一私有备份与并发修改检查，见 [CLI 管理](CLI_MANAGEMENT.md)。

package/docs/HEADLESS_CLI.md

@@ -1,15 +1,23 @@
 # Headless CLI
 
-`run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。0.2.4的六类功能均采用明确分配名单，升级差异见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+`run music` 支持音乐生成与模型级协议配置，见 [音乐生成](MUSIC.md)。0.2.6 可选择自动池、仅用所选模型或停用，旧名单和空配置不自动改变，见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
-本文面向Iris0.2.5，涵盖无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.5` 后运行 `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
@@ -18,7 +26,7 @@ dsh-iris capabilities list --provider-config /absolute/path/to/providers.json
 dsh-iris doctor --data-root /absolute/path/to/iris-data --json
 ```
 
-前两项只读取显式提供的私有配置文件，不创建Core Runtime或数据根，也不请求Provider。`providers list`输出供应商身份、启用/配置状态、认证方式、媒体协议及其推断标记、配置能力与模型数；不输出API Key或端点。0.2.4的 `capabilities list` 按六种配置能力列出明确分配且当前CLI可用的 `providerId::modelId` 候选链；空链标为 `gap: no_configured_model`。这些只是配置事实，不证明远端模型或协议可调用。
+前两项只读取显式提供的私有配置文件，不创建 Core Runtime 或数据根，也不请求 Provider。`providers list` 输出供应商身份、启用/配置状态、认证方式、媒体协议及其推断标记、配置能力、模型数和已有目录摘要；不输出 API Key 或端点。`capabilities list` 按六类功能的当前策略列出 CLI 可用的 `providerId::modelId` 候选链；空链标为 `gap: no_configured_model`。这些只是配置和历史证据，不证明远端模型或协议可调用。
 
 显式 `doctor --data-root` 是只读 Core 盘点：检查 Task/Artifact 结构、Index 一致性、孤立/未解析条目和写者租约；不创建缺失的根、不执行写入探针、不重建索引，也不释放租约。活跃写者可能使盘点在读取期间变化。省略 `--data-root` 时仍检查 DSH profile，保留原有写入探针，并纳入该 profile 的 `core-v0`。两种模式都返回 legacy/Core 计数对照，显式模式只统计指定根同层的 legacy 文件。退出码为 `0` 正常、`1` 警告、`2` 硬错误；诊断不会调用 Provider。
 
@@ -75,11 +83,11 @@ dsh-iris run image \
   --input '{"prompt":"一朵雨后的鸢尾花","model_ref":"provider-id::model-id","size":"1024*1024","n":1}'
 ```
 
-`model_ref` 可省略；省略时只使用assignment名单，按配置顺序选择。指定时须属于名单且本次只调用该项。每个请求从首项开始，只有明确 `not_accepted` 才进入下一项。配置文件须为普通文件，POSIX权限不得开放给group/other；API Key、端点、Prompt和下载URL都不会写入Task输出。
+`model_ref` 可省略；省略时按当前功能策略选择候选，自动池按登记顺序，手选模式按名单顺序，停用不调用。指定时须属于当前允许范围且本次只调用该项。每个请求从首项开始，只有明确 `not_accepted` 才进入下一项。配置文件须为普通文件，POSIX 权限不得开放给 group/other；API Key、端点、Prompt 和下载 URL 都不会写入 Task 输出。
 
 模型必须存在于配置的 `models` 或旧模型字段中，且具备所请求的能力；缺失时返回配置错误，不注入厂商默认模型。显式 `models:[]` 表示没有可用模型。`model_ref` 也接受裸模型名，同名跨供应商时从当前功能名单中取首个匹配项；需要精确绑定账号时使用 `providerId::modelId`。显式指定只选择该模型，不扩展 failover 候选。
 
-裸 DashScope 账号不再自动写入厂商目录或授予功能能力。已有明确保存的模型和旧能力字段绑定继续保留；独立 CLI 配置同样需要声明模型并分配给功能。
+裸 DashScope 账号不自动写入厂商目录或授予功能能力。已有明确保存的模型和旧能力字段绑定继续保留；独立 CLI 配置同样需要声明模型用途，并明确启用自动池或配置手选名单。
 
 生图按每个模型的有效图片协议调用，保存真实 PNG/JPEG/WebP 字节。聊天改图使用 `source_artifact_id`，创建关联原图的新 Artifact；具体参数和协议限制见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议) 与 [Artifact 聊天改图](CLI_MANAGEMENT.md#artifact-聊天改图)。
 
@@ -138,7 +146,7 @@ dsh-iris task inspect task_0123456789abcdef01234567 \
 
 新建 Attempt 可选保存 `stageTimestamps`：排队、开始提交、提交响应、远端终态、开始下载、下载校验完成和本地 Artifact 处理完成七个边界。字段按发生顺序单调不减；旧记录缺失该字段仍可读取。重新交付会从新的下载开始边界重新计时，不伪造尚未跨过的阶段。
 
-新建Attempt还可选保存 `selectionReason`：`explicit` 表示调用方明确指定名单内模型，`assignment` 表示按提交当时的功能名单选择。`pool` 保留为旧记录的历史来源，0.2.4不再产生池补齐候选。该事实随Attempt在Provider submit前落盘；`task inspect` 只展示持久记录，不按当前assignment事后猜测。旧记录缺少字段时保持缺失；第几次failover仍看 `ordinal`。
+新建 Attempt 还可选保存 `selectionReason`：`explicit` 表示调用方明确指定允许范围内的模型，`assignment` 表示按提交时的手选名单选择，`pool` 表示自动池选择。0.2.4/0.2.5 不产生新的池补齐候选，0.2.6 在主动启用自动池后使用 `pool`。该事实随 Attempt 在 Provider submit 前落盘；`task inspect` 只展示持久记录，不按当前策略事后猜测。旧记录缺少字段时保持缺失；第几次 failover 仍看 `ordinal`。
 
 已受理的异步图片 Task 可以显式推进一次：
 
@@ -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_ADAPTER_CONTRACT.md

@@ -2,6 +2,8 @@
 
 状态：**v0.1.4 内部契约与渐进迁移已完成，并通过真实 DSH 隔离 canary。** 本文固定真实消费者所需的最小边界；0.2.2 已提供独立 Core/CLI，但未冻结公开 Host SDK，也未实现完整 Local Host。
 
+Iris 0.2.6 增加 [三种功能池策略](FUNCTION_MODEL_POOLS.md)；下文“功能名单”在 0.2.6 中指当前功能允许范围，自动池也遵守相同的 Host 边界。0.2.4/0.2.5 采用严格名单。
+
 ## 目标
 
 Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、会话、浏览器和模型能力映射为 Iris 端口。Command 接收 Iris 输入、`AbortSignal` 和所声明的 Host Port，**不得接收原始 `ctx`**。Task、Provider、文件持久化和成本语义不属于宿主。
@@ -20,10 +22,13 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | `sessions` | `ctx.get('sessionQuery')` / Client sessions | 列出当前会话的受支持附件和最小模型选择信息 | 只使用 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 服务 | 列出无密钥的连接元数据；仅在服务端操作期间解析所引用连接 | 连接引用不可用，手动供应商不受影响 |
 | `visionModel` | DSH 旧视觉桥接 | 保留 `analyze()` 兼容入口；当前视觉共享端口经 `textModel` 与附件桥接执行 | 旧桥接不可用，不自动授予视觉功能调用资格 |
 
 `ports` 只包含真实可调用的方法对象。缺失或版本不兼容的能力进入 `unavailable`，并提供 `kind` 与人类可读 `reason`；Doctor 与运行错误必须消费同一份事实。
 
+0.2.6 在 DSH 适配边界使用 `providerConnections.list()` 和 `resolve(reference, { signal })`。前者不读取密钥值，后者只返回操作期间的服务端连接信息；Core 接收已经解析的普通 Provider 参数，不接收该端口、DSH 对象或凭据引用。使用 DSH 连接的生成、发现、视觉及任务恢复条件依赖此端口，普通手动配置不依赖。详见 [连接复用](DSH_PROVIDER_CONNECTIONS.md)。
+
 ## Command × Host Port 矩阵
 
 | Command/入口 | 必需端口 | 可选端口 | 说明 |
@@ -43,7 +48,7 @@ Host Adapter 只负责把一个宿主的工具、路由、客户端、附件、
 | Workbench/API/媒体路由 | `routes` | `clientSlots` | HTTP/UI 只是投影，不是真相来源 |
 | 随包 Skill | `skills` | 无 | Skill 不得绕过 Command、Task 或费用边界 |
 
-开发树中的宿主视觉必须以 `host:current-vision` 加入视觉名单并排序；读取的是DSH当前默认选择，不是当前对话选择。不自动追加宿主候选，临时指定失败也不回退。升级规则见 [功能模型分配](FUNCTION_MODEL_ASSIGNMENTS.md)。
+宿主视觉必须以 `host:current-vision` 加入视觉名单，或在自动池中明确启用宿主视觉；读取的是 DSH 当前默认选择，不是当前对话选择。不自动追加宿主候选，临时指定失败也不回退。升级规则见 [功能模型池](FUNCTION_MODEL_POOLS.md)。
 
 ## 不可违反规则
 
@@ -86,7 +91,7 @@ Iris 继续作为普通 DSH/Cordis 插件装载：`cordis.patch.yml` 只把 npm
 ## 当前覆盖
 
 - `lib/index.js` 负责 DSH 插件入口、生命周期和工具注册；
-- `lib/dsh-host-adapter.js` 映射九类命名端口；
+- `lib/dsh-host-adapter.js` 映射上述命名端口；
 - Local Host fixture 覆盖 crop/diff、Task 查询与提醒操作，并验证缺失能力的错误；
 - Host Doctor 对服务端注册账本、客户端版本和 Slot 握手分别给出结果；
 - 已发布 Iris `0.1.4` 在 DSH `0.1.2-rc.1` 与 `0.1.5-rc.1` 上有历史宿主验证记录，不继承为当前版本的支持声明。

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.4检查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)。
 
@@ -23,7 +23,7 @@ Host Doctor 是 Iris 在运行中的 DSH 实例内提供的兼容性诊断。它
 /iris/api/doctor
 ```
 
-这是工作台路由下的 JSON 端点，继承 Iris 路由的 Host/认证边界。HTTP 200 表示诊断成功生成，不代表所有检查健康；应读取响应中的 `exitCode`：
+这是工作台路由下的 JSON 端点，使用 Iris 的回环/显式 trusted Host 和浏览器来源守卫；这些检查不提供身份认证，也不能假定该路径继承 DSH `/api` 的认证。对外暴露时须由部署者提供认证和访问控制，见 [安全边界](SECURITY.md)。HTTP 200 表示诊断成功生成，不代表所有检查健康；应读取响应中的 `exitCode`：
 
 - `0`：当前可观察项全部健康；
 - `1`：存在可降级警告，例如页面尚未打开、可选 Browser 缺失；
@@ -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。