@mokuyoaxis/dsh-iris 0.2.6 → 0.2.7

package/docs/LOCAL_API_CONTRACT.md

@@ -0,0 +1,115 @@
+# 独立本地 API 契约（0.3 / I4）
+
+0.2.7 已实现 **I4A 默认只读**与 **I4B 显式本地创建**：显式本机监听、Bearer/Host/Origin、受控流程/媒体，以及主动启用的上传/创建与持久身份接回，见 [只读 API](LOCAL_API.md)和 [本地创建](LOCAL_CREATION.md)。**继续/选择、Operation 与执行取消仍是设计稿**；本契约尚未冻结为公开 SDK，上述 I4A/I4B 入口随 npm 0.2.7 分发。
+
+当前固定流程的真实执行入口仍是 [CLI](IMAGE_FLOW.md)；[独立 Web Demo](WEB_PROTOTYPE.md)只消费内存演示，保留到 0.3.0 阶段统一润色。它尚未接入只读 API，也不作为完整服务或写操作已经实现的依据。
+
+## 1. 实例与启动
+
+一个服务实例显式绑定一个已初始化的专用 Flow 根和一个 Application Runtime。Provider 配置来源可显式提供，省略时仍可查看已有流程/图片，启用本地写入后也可上传；模型列表返回未配置，不能创建新 Run。由用户主动启动，固定仅监听 `127.0.0.1`；首次不支持远程监听、代理转发或自动扫描 DSH 配置。CLI 的 `flow init` 仍负责初始化新根，浏览器不能指定根路径、初始化旧根或变更 Provider 配置。
+
+API 使用 `/api/v0` 前缀，后续静态页面须与 API 同源。只有 HTTP 适配器负责验证外部输入、生成受控 DTO 和管理请求；不得把 `application.execute(name, input)`、现有 DSH `serveApi` 或 CLI 参数作为通用 HTTP 转发口。模型来自显式配置中允许改图的候选，Flow 继续绑定单一明确模型与 `n=1`。
+
+I4B 的上传与 Run 创建均不生成，完成本地提交后返回 201，同 Key 接回返回 200。`api init` 先在空的已初始化 Flow 根建立请求区，`api serve --allow-local-writes` 才开放这两个 POST，不自动转换已有创作根。默认启动仍只读。
+
+## 2. 身份与浏览器边界
+
+- 每次启动产生 32 字节随机会话 Token，CLI 通过必填 `--token-file` 写入新的根外私有文件（POSIX 0600），不打印 Token。服务鉴权使用 Token 摘要和等时比较；调用进程读取私有文件，以 `Authorization: Bearer …` 发送，不进入 URL、命令行参数、Run、日志或错误文本。未来浏览器只在标签页内存保留 Token；页面重新连接不开始生成。首版文件交付替代最初的终端显示提案，支持自动化且避免管道日志收集 Token。
+- **所有 API，包括模型列表、状态与媒体，都验证身份**；Token 比较使用等时比较。首版不使用 Cookie，也不建立“同源就已认证”的假设。退出页面丢弃客户端 Token；停机使该进程 Token 失效。
+- `Host` 必须精确匹配实际监听 authority。带 `Origin` 的请求仅允许该页面精确 origin；`Origin: null`、外站 origin 和不匹配 Host 拒绝，不采信 `Forwarded` 或 `X-Forwarded-*`。无 Origin 的本机 CLI 请求仍须通过 Host 与 Token 检查。不同 origin 的 OPTIONS 不开放 CORS。
+- 当前 API 响应使用限制性 CSP。未来页面的脚本/样式只从本站加载，无内联脚本、第三方资源、对象、框架嵌入或表单提交；用户内容用文本节点展示，媒体通过带认证的 fetch 获取 Blob 后展示/下载，不将 Token 放入 `<img>` URL。
+- JSON、状态、媒体和错误响应使用 `Cache-Control: no-store`、`X-Content-Type-Options: nosniff`；API 不重定向到 Provider URL。首切片仅为意外服务错误记录净化调用帧与关联 ID。若增加访问日志，只记录方法、固定路由类型、状态、随机关联 ID 与耗时，不记录 Authorization、正文、查询参数或绝对路径。
+
+Bearer、Host/Origin 与 CSP 是不同边界，不能相互替代。静态预览器没有凭据或 Core 权限，它的验证不等于这里的认证验收。
+
+## 3. 有限路由
+
+下列除 Operation 外的 GET 路由已实现，并支持同样鉴权的 HEAD；I4B 只实现 images/runs 两个 POST，其他 POST 与 Operation 查询仍是提案。JSON 响应含 `contractVersion: 0`；列表最多 30 项，摘要不含 Prompt；创建 JSON 上限 64 KiB，Prompt 使用现行生成输入约束。未知/重复查询参数和带正文的只读请求拒绝。
+
+| 方法与路径 | 输入 | 语义 |
+|---|---|---|
+| `GET /session` | 无 | 返回实例标识、契约版本、允许的操作与输入上限；不返回根路径、Key 或端点 |
+| `GET /models` | 无 | 返回当前可选的 `modelRef`、显示名和是否支持改图；不会探测 Provider、同步目录或修改用途 |
+| `POST /images`（I4B） | 原始 PNG/JPEG/WebP 字节、匹配的 Content-Type、Idempotency-Key | 本地提交后返回 201 和 Artifact 引用，同 Key 接回返回 200；不接受文件路径、URL、目录或 SVG |
+| `GET /runs` | `cursor`、`limit`，limit 1–30 | 已有流程摘要，不含 Prompt；只读，不观察远端 |
+| `POST /runs`（I4B） | `{sourceArtifactId, modelRef, prompt, size?}`、Idempotency-Key | 固定 `image-edit/v0` / `n=1`，只保存输入与身份，零生成请求；本地提交后 201，同 Key 接回 200 |
+| `GET /runs/:id` | 无 | 返回下述 FlowView；只读，不创建 Task、补交付或继续步骤 |
+| `POST /runs/:id/continue` | 空 JSON、Idempotency-Key | 显式首次提交、单次观察原任务、补交付或本地比较；不重提已有 Attempt |
+| `POST /runs/:id/selection` | `{artifactId}`、Idempotency-Key | 只接受该 Run 的原图/新版；不触发生成或下载 |
+| `GET /artifacts/:id/content` | 无 | 按已验证 Artifact ID 和清单读取该根内媒体字节，不接受 path/URL 参数；不写文件 |
+| `GET /runs/:id/download` | 无 | 返回已选择图片的原字节及受控附件名；未选择则冲突，不接受服务器输出路径 |
+| `GET /operations/:id`（待实现） | 无 | 查询本实例操作状态，不能借此继续操作 |
+| `POST /operations/:id/cancel` | 空 JSON | 停止本次排队/等待，幂等；不代表远端生成已撤销或已退款 |
+
+上传累积读取限制使用现有 `MAX_IMPORT_IMAGE_BYTES = 20 MiB`，不能只相信 Content-Length；最终交给 `readImportImage({imageBytes}, signal)` 检查实际格式和静态图片要求。连接关闭、超量与解析失败不留下临时可服务文件，不把 filename 当服务器路径。并发上传上限 1，超过返回忙；用户显式重试复用原 Key。
+
+上传复用现有图片验证与 Artifact 预留 ID 提交；请求与作品在同一次 writer 内保存。当前图片读取/下载仍限 64 MiB，类型 PNG/JPEG/WebP，先检查清单大小再校验内容哈希，最多两个活动读取。大型媒体磁盘流式、Range 和音视频仍待后续。下载不调用服务器本地 `flow.export(output_path)`；浏览器是否保存成功不属于持久 Run 事实。
+
+## 4. FlowView 与操作反馈
+
+浏览器只消费白名单投影，不直接接收磁盘 Run、完整 Task、Attempt、Provider 错误对象或配置。完整详情是用户创作数据，需要认证；摘要不包含 Prompt。
+
+```text
+FlowView {
+  contractVersion: 0,
+  id, recipe: "image-edit/v0", revision, createdAt, updatedAt,
+  status: not_started | running | needs_attention | delivery_failed |
+          needs_comparison | awaiting_selection | selected,
+  input: { prompt, modelRef, size? },
+  source: { artifactId },
+  output: { artifactId } | null,
+  comparison: { artifactId } | null,
+  selection: { artifactId } | null,
+  task: { id, acceptance, outcome, deliveryState, attemptCount } | null,
+  metrics: { ratio, diffPixels, totalPixels, width, height } | null
+}
+```
+
+ID 继续使用当前 `run_` / `task_` / `artifact_` 加 24 位小写十六进制。DTO 不带绝对路径、端点、绑定摘要、远端任务 ID 或任意媒体 URL。媒体信息如格式/尺寸应由独立受控投影提供，不信任用户文件名。`metrics` 仅来自实际已提交比较作品；像素差异不是质量评分。
+
+| `status` | 首要操作与文案边界 |
+|---|---|
+| `not_started` | “开始生成”；可能产生费用，输入已经固定 |
+| `running` | “查看原任务”；每次显式操作至多观察一次，页面不自行调用 continue |
+| `needs_attention` | 显示受理未知/失败/取消等事实；无自动重提。需要新生成时明确新建 Run |
+| `delivery_failed` | “恢复结果”；生成已经成功，恢复原缓存/远端结果，不新生成 |
+| `needs_comparison` | “完成比较”；执行本地步骤，不新生成 |
+| `awaiting_selection` | 选择原图或新版；下载仍禁用 |
+| `selected` | 可下载；不能据此声称文件已经保存到用户设备 |
+
+I4B 的上传与创建同步完成本地提交，以 201/200 返回 Artifact/FlowView 和 `idempotentReplay`，不返回持久排队的 202，也不开放 Operation 查询或取消。相同 Key 保证原业务身份与效果；已有 Run 的返回状态可以随真实进度变化，不承诺重放完全相同的响应字节。
+
+后续异步执行拟在持久接收后返回 `202 {contractVersion:0, operationId, runId?}`，状态为 `queued | running | succeeded | failed | interrupted`。GET 轮询只能读取，不能驱动 Provider；原任务的远端观察必须显式点击。实例内拟最多一个活动 writer、8 个等待写操作；同一 Run 已有活动 continue 时，新 Key 返回冲突，同 Key 接回原 Operation。取消直接中止对应控制器，不能排在被取消 writer 后面；停止等待不伪造远端 Task canceled。这些执行/Operation 语义须另行实现和验收，不随 I4B 自动开放。
+
+## 5. 上传与持久创建幂等（I4B）
+
+I2 保证相同 Run 使用原 Task；I4B 另保证同 Key 创建请求接回原 Artifact/Run。前端禁用按钮、内存 Map 和“成功后才写 Key → Run 映射”不能代替持久意图。
+
+新空专用根使用 `creation-requests/v0/root.json` 和 `requests/req_<64 hex>.json`，没有数据库或已有创作根迁移；现有 Task/Artifact/Run 格式保持。具体约定为：
+
+1. 客户端每次明确动作使用一个不带引号的小写 UUIDv4 `Idempotency-Key`。请求区保存稳定 rootId；命名空间按 rootId、操作种类和 Key 计算 SHA256，**不使用随重启变化的服务 instanceId、Token、端口或本机路径**。原始 Key 不持久保存或记录。
+2. 输入摘要来自规范化内容：图片的真实字节摘要、大小与 Content-Type；Run 的来源 ID、模型引用、规范化 Prompt/size、固定 recipe/n。对象键序不影响摘要，不额外改写正文。同 Key 不同内容 409；已发布意图不因模型池或端点变化另选身份。
+3. 同一个 operation-owned Core writer 内，先校验新输入并**排他发布 prepared 意图与全部预留身份**，再提交 Artifact/Run，最后原子更新 succeeded。不能通过两个独立 writer 或“先创建后补 Key 映射”实现。创建 Run 需内部受控的预留 Run/Task/比较作品 ID，浏览器不能指定它们。
+4. 已存在的 Run 按原始输入、来源/binding、创建时间和预留身份核对；允许后续 revision、输出或选择已经推进，返回当前事实，绝不覆盖回初始状态。图片复用现有 Artifact 重入提交及内容校验；未完成上传不另存原件，需客户端同 Key 重新提供相同字节。
+5. 意图发布前的验证失败、busy 或排队取消不消费 Key；发布后的断线不撤销已经接受的本地提交。启动、GET 和刷新不自动修复/重放；显式同 Key POST 才核对或补完。存储损坏或身份冲突保留现场，不能回退成随机新建；不永久缓存通用 500 并把原对象藏起来。
+6. prepared 引用保护包括预留上传对象、Flow 来源/Task/比较身份；succeeded 保留请求身份和原结果 ID，但不额外禁止显式删除未使用的上传，真实 Run/Task 引用仍保护。成功目标不可用时，同 Key 返回 `409 IRIS_API_RESULT_UNAVAILABLE`，不复活作品或重建 Run。损坏/未知请求阻止误清理，不能当作空引用；首版没有请求删除、TTL 或自动 GC，权限沿用私有约定。
+7. 新版 writer 和维护入口必须识别请求格式，未知/半初始化请求区拒绝写入。已发布旧程序没有这些新检查，不能靠一个标记保证其拒绝该根；此专用根只支持已验收的 request-aware writer，回退使用完整副本，不删除请求区伪装降级。已提交 Flow/图片仍可只读查看。
+8. 复用现有原子发布和重入能力，验证范围限进程异常退出/SIGKILL；不据此承诺断电、操作系统崩溃或共享存储下的跨文件事务。请求区本身不触发 Provider 目录刷新、探测、生成或任务观察。
+
+后续 continue/Operation 仍需独立的持久接收与中断协议；重启只展示未完成事实，**不能自动重放 continue**。I4B 的本地创建与中断证据不能代替可能计费的执行验收；开始按钮接入实际生成前，仍须补执行接收、未知受理、取消和停机测试。
+
+## 6. 错误与验收
+
+统一错误外形为 `{contractVersion:0, error:{code, message, requestId}}`，不附堆栈、配置或 Provider 原始响应。网络错误只返回已脱敏的有限分类；取消/断线不把未知改写为失败未计费。
+
+| HTTP | 类别 |
+|---|---|
+| 400 / 413 / 415 | 输入无效、正文过大、图片格式不支持 |
+| 401 / 403 | 身份无效、Host/Origin 不可信 |
+| 404 | 合法 ID 在该实例不存在 |
+| 409 | Key 输入冲突、原任务状态冲突、根被占用、同一 Run 操作活跃、尚未选择 |
+| 429 | 有界队列/上传已满，显式重试可复用原 Key |
+| 503 | 正在关闭；不再接收新写操作 |
+| 500 | 无法分类的内部错误，保留服务端关联证据并停止相应操作，不静默回退 |
+
+I4 必须实际验证：错误 Token/Host/Origin、媒体绕过、超量流式上传/损坏图片/路径参数、双击/不同 Key 并发、同 Key 响应丢失/重启、未知受理不重提、只读重连、取消时序、停机与租约释放。之后才让 [Web 原型](WEB_PROTOTYPE.md)换成真实传输并验收无 DSH 的端到端路径。本稿和静态预览不等于第二个生产 Host 已完成。

package/docs/LOCAL_CREATION.md

@@ -0,0 +1,50 @@
+# 本地上传与流程创建（0.2.7 / I4B）
+
+0.2.7 在 [只读本地 API](LOCAL_API.md)之上，增加显式启用的图片上传和固定 Run 创建。两者都只提交本地数据，不生成、不观察任务、不调用 Provider。实际生成仍使用 [Flow CLI](IMAGE_FLOW.md)；执行/取消 API 与真实 Web 接入留到后续。本功能从 npm 0.2.7 起随包分发。
+
+## 初始化与启用
+
+为这一功能选择新的专用根，先初始化 Flow，再初始化请求区：
+
+```bash
+dsh-iris flow init --data-root /absolute/path/new-flow-core
+dsh-iris api init --data-root /absolute/path/new-flow-core
+dsh-iris api serve --data-root /absolute/path/new-flow-core --token-file /absolute/private/session-001.token --provider-config /absolute/private/providers.json --allow-local-writes
+```
+
+`api init` 只接受空的已初始化 Flow 根，不转换已有创作数据。重复初始化返回原 rootId；半初始化、未知版本或损坏请求区报错并保留现场。省略 `--allow-local-writes` 时仍只读；没有 Provider 配置也可上传或读取已有结果，创建新 Run 需要显式的可改图模型配置。
+
+服务仍固定监听 `127.0.0.1`，默认随机端口；Token 文件与身份、Host/Origin、停止方法沿用 [只读入口](LOCAL_API.md)。Token 和请求 Key 是两件事：每次启动换 Token，同一次创建在网络不确定时保留原 Key。不要通过 URL、命令行参数或共享日志传 Token。
+
+## 两个本地写接口
+
+每次明确的新动作产生一个不带引号的小写 UUIDv4 `Idempotency-Key`，发送单个请求头。该 Key 不代替 Bearer 鉴权。
+
+| 路径 | 输入 | 返回 |
+|---|---|---|
+| `POST /api/v0/images` | 原始静态 PNG/JPEG/WebP 字节，匹配的 Content-Type，最多 20 MiB | `{contractVersion:0,idempotentReplay,artifact:{artifactId,mediaType,size,width,height}}` |
+| `POST /api/v0/runs` | UTF-8 JSON `{sourceArtifactId,modelRef,prompt,size?}`，最多 64 KiB | `{contractVersion:0,idempotentReplay,flow:<FlowView>}` |
+
+首次创建在本地提交完成后返回 201；同 Key、同规范化输入接回原身份，返回 200 和 `idempotentReplay: true`。同 Key 不同输入返回 409；新的 Key 表示另一明确创建，不做全局按内容去重。Run 固定 `image-edit/v0`、单一明确模型和 `n=1`，创建不建立实际 Task。模型配置只读解析，不刷新目录或实测能力。
+
+上传不接受路径、URL、文件名、SVG、动画或压缩正文；真实格式必须匹配 Content-Type。累计读取限额不只依赖 Content-Length，同时最多一个上传、最多九个本地创建请求；繁忙返回 429，同物理根有其他 writer 时返回 409，显式重试保留原 Key。
+
+超限返回 `413 IRIS_API_INPUT_TOO_LARGE`，不创建作品或消费 Key。对尚未结束的上传，先发送完整错误响应，再丢弃剩余正文并关闭连接；不继续缓存正文，连接仍受现有请求/空闲超时和服务停止约束。客户端收到拒绝后应停止上传。
+
+当前没有 `POST /runs/:id/continue`、selection、Operation 查询或取消接口。GET、HEAD、页面刷新和启动不自动执行或补完创建；现有 Demo 仍使用演示传输，尚未连接这个 API。
+
+## 重试、删除与中断
+
+请求意图、预留身份、业务提交和完成状态共用同一次 Core writer。跨进程重启、端口变化或 Token 轮换后，同 Key 仍绑定原数据根和原输入；已有 Run 后续执行或选择过，重放返回其当前 FlowView，不回退进度。已有意图不因当前 Provider 配置变化另选模型/端点，未来执行仍遵守原 Flow binding。
+
+意图发布前的输入错误、busy、排队取消或断线不消费 Key；发布后断线不撤销本地提交。未完成上传需要重新提供相同字节；显式同 Key POST 才核对或补完，没有自动后台重放。关闭服务会停止接收和等待，并保留未完成证据。
+
+未完成请求引用的来源与预留对象受删除/清理保护。成功上传如果没有其他 Run/Task 引用，仍可通过现有明确动作隔离或删除；之后同 Key 返回 `409 IRIS_API_RESULT_UNAVAILABLE`，不复活作品或新建替代身份。请求记录首版不自动过期、删除或 GC。
+
+## 数据与版本边界
+
+新私有请求区为 `creation-requests/v0`；现有 Run、Task、Artifact 格式保持，未迁移 DSH 日常数据。未知/损坏请求区使新版 writer 和维护操作报错，reader 仍可只读查看已有有效 Flow/图片。
+
+此专用根只支持认识请求格式且通过验收的 writer。旧 binary 没有新检查，不能靠一个新目录保证它拒写；不要用旧版本对该根执行写入。需要回退时使用改动前完整副本，不删除请求区伪装降级。半初始化现场不自动修复，优先另建新空根。
+
+验证范围为进程异常退出与 SIGKILL 下的身份接回；现有文件原语没有显式 fsync，不承诺断电、操作系统崩溃或 Android 共享存储上的跨文件事务。Windows/macOS 与真机使用范围须独立验证。

package/docs/PROVIDER_HEALTH.md

@@ -1,6 +1,6 @@
 # Provider 与能力健康状态
 
-版本要求：**Iris 0.2.6**。包含能力检测、目录与模型可用性；沿用短时限流冷却、明确额度/预算耗尽停用及持久健康证据。发布状态见 [README](../README.md)。
+本文对应 **Iris 0.2.7**，本页检测入口从 0.2.6 起提供。包含能力检测、目录与模型可用性；沿用短时限流冷却、明确额度/预算耗尽停用及持久健康证据。发布状态见 [README](../README.md)。
 
 工作台的“能力状态与检测”与 [功能模型池](FUNCTION_MODEL_POOLS.md) 配套；以下健康证据规则继续适用。
 

package/docs/ROADMAP.md

@@ -4,7 +4,7 @@ Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用
 
 ## 当前状态
 
-本文对应 **Iris 0.2.6**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI；本版增加连接复用、可选自动池和目录同步，详见 [0.2.6 发布说明](releases/0.2.6.md)。
+本文对应 **Iris 0.2.7**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI；本版增加截图修复、实例运行时、持久图片流程、本地 API 和 Core Skill 安装，详见 [0.2.7 发布说明](releases/0.2.7.md)。
 
 - 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
 - 持久图片导入与原生 Qwen 改图；六类功能可选自动池、手选或停用，宿主视觉需明确启用。0.2.5 建立的 12 个准确 DSH 版本范围保持。
@@ -18,6 +18,18 @@ DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视
 
 宿主兼容继续集中在Adapter与客户端桥接。后续DSH更新优先检查实际API、工具/附件交付和输入区契约，复用同一验收入口扩充版本矩阵，避免让旧用户长期停留在缺少新功能的Iris分支。
 
+## 0.2.7 基础设施与 0.3.0 方向
+
+宿主 HTML 截图已适配浏览器返回的 PNG 数据，并增加实际监听地址解析和用户主动触发的截图自检，见 [0.2.7 发布说明](releases/0.2.7.md)与 [宿主诊断](HOST_DOCTOR.md#截图地址与主动自检027)。
+
+0.3 基础设施已接入首批 [内部应用运行时](CORE_RUNTIME_CONTRACT.md#应用运行时装配)与 [固定改图流程](IMAGE_FLOW.md)：实例写队列、稳定 Run/步骤与 Task 绑定、原任务/比较图恢复、引用保护和明确选择/导出。
+
+[DSH Core 装配](DSH_RUNTIME.md)也已迁入实例：写入共用应用队列，连接解析引用、观察器和启动接管由插件持有，卸载等待在途操作。原根与业务保持；legacy 配置等存储仍未实例化，Flow 尚未接入 DSH 工作台。
+
+0.2.7 已有 [I4A 默认只读 API](LOCAL_API.md)与 [I4B 本地创建](LOCAL_CREATION.md)：显式回环监听、Bearer/Host/Origin、受控图片，以及新空根主动启用的上传/Run 创建和持久 Key 身份接回。GET 不执行步骤，本地创建也不生成；有限执行/取消与 Operation 仍按 [API 契约](LOCAL_API_CONTRACT.md)继续。
+
+源码树保留 [面向 0.3.0 的独立 Web Demo](WEB_PROTOTYPE.md)，用于说明输入、状态、比较与选择的操作方向。当前只消费演示数据，不连接模型、不计费，也未接入 API；界面与交互细节留到 **0.3.0 阶段统一润色**。后续补执行接收、取消和恢复验收，再接入实际工作台。通用 Recipe 与实际独立工作台尚未完成，没有已承诺的发布日期。
+
 ## 近期优先：真实使用验收
 
 优先完善图片创作与配乐、短片素材准备等完整流程：复用已有作品、按需生成、试听或查看结果，再导出可继续处理的素材。分别交付音视频素材不等于自动混音成片。
@@ -40,7 +52,7 @@ DSH 工作台与 Headless CLI 共用 Core 的可恢复隔离和恢复入口，
 - Core 隔离内容的永久 purge（0.2.1 已开放可恢复隔离/恢复，legacy 永久删除保持原行为）；
 - 鸢尾花与泡泡视觉身份；
 - 有可用接口与实际需求后，补 Images 编辑、mask、多参考图或连续编辑；
-- 将提示词优化收口为 Core Prompt Engine 与共享 `prompt.optimize` Command，由 CLI 和 DSH 入口共同消费；DSH 只负责草稿读取、预览和写回；
+- 在已有纯核心提示词实现上补共享 `prompt.optimize` Command 与 CLI 消费；DSH 负责草稿读取、预览和写回；
 - 冻结中立 TextModel Port，把 Ollama、兼容文本端点及其他文本模型后端与媒体 Provider Catalog 分离，避免通用文本模型淹没 Iris 媒体模型界面；
 - 接入 ComfyUI、本地 TTS 等本地媒体 Provider，并补齐 `auth: none`、`billing: none`、同步完成语义和本地/远程 UI 区分；
 - 有可信价格来源后的成本与策略展示。

package/docs/SECURITY.md

@@ -1,6 +1,6 @@
 # Iris 安全边界
 
-版本：Iris 0.2.6，发布状态见 [README](../README.md)。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
+版本：Iris 0.2.7，发布状态见 [README](../README.md)。安全目标是避免凭据泄露、路径越权、跨站写入和因错误重试造成重复计费；Iris 与 DSH 仍是本机同一信任域内的预览软件，不构成多租户安全边界。
 
 ## 信任模型
 
@@ -52,6 +52,14 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 - SSE 使用同源连接、节流和背压合并；慢消费者只保留最新快照，避免积压历史状态。
 - 如果把 DSH 通过 LAN、反向代理或隧道暴露，必须由部署者另加真正的认证、TLS、访问控制和来源限制。
 
+## 显式本地 API 与 Skill 安装
+
+0.2.7 的 [本地 API](LOCAL_API.md)由用户显式启动，只监听 `127.0.0.1`，与 DSH 路由的身份边界分别管理。每次启动产生独立会话 Token，写入新的根外私有文件；全部 API 与媒体都要求 Bearer、准确 Host 和受控 Origin，不将 Token 放入 URL 或 stdout。服务关闭后旧 Token 失效，原私有文件保留。
+
+默认 GET/HEAD 不写 Core 或调用 Provider。新空 Flow 根须显式 `api init`，并通过 `--allow-local-writes` 开启 [上传/创建](LOCAL_CREATION.md)；这两个 POST 不执行生成。请求意图与业务效果在同一 writer 内提交，同 Key 接回原身份，损坏请求保留并拒写，成功结果删除后不自动复活。固定流程的 Prompt 保存为专用根中的私有 Run 输入，不进入公共 Task/Artifact DTO；备份该根时应按私人创作数据保护。旧 writer 不得写入新流程根，回退应使用完整备份。
+
+[Core Skill 安装器](CORE_SKILLS.md)只有显式 `skills install/uninstall` 才修改目标，`status` 与 dry-run 只读。安装记录用于内容与归属检查，不能作为对恶意本机用户的认证。无归属目录、用户修改及软链不被接管；升级/卸载保留扫描根外备份，不自动清理。安装不改变模型、MCP 或宿主权限；文件完整不等于宿主已发现 Skill，也不等于 Agent 已完成业务验收。
+
 ## 图像处理依赖
 
 0.2.6 将 `sharp` 最低版本提高到 `0.35.5`，锁文件同步其修复后的预编译依赖，以处理 [librsvg 高危公告 GHSA-wq5f-xc86-pv6w](https://github.com/lovell/sharp/security/advisories/GHSA-wq5f-xc86-pv6w)。公告涉及特定 glibc Linux 运行条件下的 SVG 内存安全问题；这不是本项目已发生利用的证据。只检查文件扩展名不能代替更新解码器。

package/docs/SYNC_DELIVERY_RECOVERY.md

@@ -2,6 +2,8 @@
 
 Iris 0.2.3 支持从缓存恢复完整同步媒体结果。本地交付失败后，可沿原任务重新交付；Task/Artifact 格式和公开 HTTP 路径保持，不需要迁移旧数据。
 
+未发布的 [固定图片流程](IMAGE_FLOW.md)也将其绑定任务的成功 poll 结果先写入原交付缓存，再按预留 Artifact ID 交付；相应中断只接回原结果，不重新 submit。未绑定 Flow 的异步 Task 沿用原路径，本节其余内容描述 0.2.3 起的同步恢复边界。
+
 ## 使用行为
 
 同步 Images、聊天生图、Responses、TTS 或音乐 返回完整结果后，本地写入失败仍记录 `accepted / succeeded / deliveryState=failed`。工作台“重新取回作品”和 CLI `task redeliver` 共用原 Task/Attempt 的恢复路径，不调用 submit、不创建新 Attempt。

package/docs/VISION_CLI.md

@@ -1,6 +1,6 @@
 # 独立视觉 CLI
 
-版本要求：**Iris 0.2.6**。发布状态见 [README](../README.md)；安装 `npm install @mokuyoaxis/dsh-iris@0.2.6` 后运行 `npx dsh-iris ...`，或从源码运行 `node bin/dsh-iris.js ...`。需要 Node.js ≥ 22、依赖 Sharp；从视频文件抽帧还需要 PATH 中的 ffmpeg、ffprobe，复用既有 Core 帧不需要。
+版本要求：**Iris 0.2.7**。发布状态见 [README](../README.md)；安装 `npm install @mokuyoaxis/dsh-iris@0.2.7` 后运行 `npx dsh-iris ...`，或从源码运行 `node bin/dsh-iris.js ...`。需要 Node.js ≥ 22、依赖 Sharp；从视频文件抽帧还需要 PATH 中的 ffmpeg、ffprobe，复用既有 Core 帧不需要。
 
 ## 四个命令
 

package/docs/WEB_PROTOTYPE.md

@@ -0,0 +1,47 @@
+# 独立工作台 Demo（面向 0.3.0，未发布）
+
+这是面向 **0.3.0** 的交互预览，用来展示“选图与填写要求 → 查看状态 → 比较 → 选择与下载”的操作方向。**当前 Demo 保留作为参考，界面、文案和交互细节将在 0.3.0 阶段统一润色，尚未定稿。**
+
+Demo 可在源码树中独立预览，无需 DSH；使用内存演示与内置样图，不连接模型、不计费，也不写入 Core 数据。真实生成目前使用现有 DSH 工作台或 CLI；npm 0.2.7 不携带源码树的 prototypes/ 和预览脚本。
+
+## 启动预览
+
+在 Git 源码树中，使用现有 Node.js ≥22，无须安装新依赖：
+
+```bash
+node scripts/preview-workbench.mjs
+```
+
+终端打印 `http://127.0.0.1:<随机端口>/`，在本机浏览器中打开。可显式指定 `--port 4173`，端口占用会报错，不自动替换。Ctrl+C 关闭。预览器只监听 loopback 并提供固定静态资源，不能读取任意仓库文件、Core 数据、Provider 配置或 `.internal/`，不会启动 DSH。
+
+不要用仓库根上的通用文件服务器代替这个入口，避免把内部资料一并提供给浏览器。页面使用 JavaScript 模块，直接双击 HTML 并不等价于上述预览。
+
+## 可体验的流程
+
+1. 使用内置鸢尾花样图，或选择/拖放本地 PNG、JPEG、WebP；本地文件只生成标签页内的 Blob 预览，不上传。
+2. 选择演示模型、填写修改要求，点击“开始演示”。本次输入随后固定；修改输入需明确新建流程。
+3. 查看原图与示例结果，切换并排/叠图，明确选择原图或结果，再下载。
+4. 展开“运行详情与演示场景”，体验原任务进行中、受理未知、生成成功但交付中断、等待本地比较等状态。场景对新流程生效。
+
+**示例结果始终是内置样图，不是对上传图片或提示词的真实修改**。原图和示例结果可能相同；原型不伪造像素差异、模型质量分数、计费价格或进度百分比。下载原图取本地原字节，下载结果取内置样图；“已选择”和“下载请求已交给浏览器”分别显示，不声称文件已保存。
+
+状态名称和白名单 DTO 依据真实 [固定流程](IMAGE_FLOW.md)；投影有实际 Core/受控 Provider 测试。演示传输不读写磁盘 Run，不保证服务重启恢复。新建后可从详情中的流程列表只读切回本标签页旧记录；整页刷新清空演示状态，并且不会自动开始。未将文件、提示词或主题写入 localStorage。
+
+“停止本次等待”只中止当前演示操作，原任务事实保留；真实 API 的远端取消须有独立能力与确认，不能把停止等待写成取消成功。展开详情、重新读取状态、切换历史与比较方式均不驱动生成。
+
+## 实现和下一步
+
+原型位于 `prototypes/workbench/`，使用原生 HTML/CSS/JavaScript，复用现有图标和示例图片，没有新框架或生产依赖。运行详情默认折叠，关闭显示“展开”、打开显示“收起”；提供浅/深色、键盘焦点与 320/390px 布局。
+
+0.2.7 已有 [默认只读 API](LOCAL_API.md)及显式开启的 [本地上传/Run 创建](LOCAL_CREATION.md)，带持久请求意图和身份接回；当前 Demo 保持原样，尚未连接它们。后续补执行/取消、Operation 与恢复边界，再在 0.3.0 阶段结合实际接口统一完善页面。Demo 的当前布局、提示词和样例效果仅用于说明方向，不代表最终界面或模型能力。
+
+[本地 API 契约](LOCAL_API_CONTRACT.md)区分已实现的只读/本地创建切片与待实现的执行、选择和取消。相同 Run 的 Task 复用与 HTTP 创建幂等分别验证；执行接口安全和中断测试通过后，再替换演示传输并完成无 DSH 的实际端到端验收。
+
+源码树可运行下面的检查；浏览器检查需显式提供已经安装的 Chromium，不下载或安装浏览器。无沙箱仅在受控测试环境确有需要时显式追加 `--no-sandbox`，不改变生产浏览器策略。
+
+```bash
+node tests/web-prototype.mjs
+node scripts/verify-workbench-prototype.mjs --browser-executable /absolute/path/to/chromium --output /absolute/path/to/new-evidence-directory
+```
+
+浏览器检查保存交互结果与桌面/手机截图；这是隔离 Chromium 验收，不是 Android 真机触控或日常 DSH 装载证明。

package/docs/releases/0.2.7.md

@@ -0,0 +1,62 @@
+# Iris 0.2.7: screenshot compatibility, persistent image workflows, and portable Skills
+
+Iris 0.2.7 fixes DSH browser screenshots and adds explicit standalone entry points for persistent image editing, local API access, and Core Skill installation. The npm package remains `@mokuyoaxis/dsh-iris`; Node.js 22.0.0 or later is required. The twelve exact DSH versions supported by 0.2.6 are unchanged.
+
+## DSH screenshots and runtime ownership
+
+- HTML screenshots consume PNG data returned by the browser and save it through Core. The browser no longer needs permission to write into the Iris data root; its download-directory restriction can remain in place.
+- Screenshot navigation uses an explicit `DSH_WEB_BASE`, otherwise the host's public listening address, and finally the historical 3080 fallback when reliable host metadata is unavailable. Public media links retain their existing base-URL contract.
+- Host Doctor distinguishes an available Browser interface from a successful screenshot. An explicit screenshot check creates a local test artifact without calling a model; ordinary diagnosis remains read-only. Cancellation closes sessions opened during the operation.
+- DSH Core operations use an instance-owned application queue, connection references, and task observers. Unload cancels and awaits active work and lease release. Existing data roots, provider protocols, and billing rules remain intact; legacy configuration storage is outside this migration.
+
+## Standalone image workflows and local API
+
+- The fixed `image-edit/v0` CLI workflow persists a Run, private inputs, step-to-Task bindings, comparison results, and the user's selection; the selected image can then be exported. Recovery reuses existing tasks and reserved artifact identities instead of submitting uncertain work again.
+- `api serve` explicitly starts a loopback-only API that is read-only by default. It exposes selected model/workflow information and controlled image access, with a private session-token file and Bearer, Host, and Origin checks.
+- A new, empty workflow root can opt into local uploads and Run creation through `api init` and `api serve --allow-local-writes`. Durable request keys reconnect repeated requests to the original result. These endpoints do not generate media; execution and cancellation APIs remain future work.
+- Rejected uploads receive the complete error before the server closes the connection, avoiding premature resets on Windows. Remaining body bytes are discarded without buffering under the existing request and idle timeouts; shutdown also closes incomplete uploads. Size, authentication and concurrency limits remain in force.
+
+See [image workflows](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/IMAGE_FLOW.md), [local API](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/LOCAL_API.md), and [local creation](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/LOCAL_CREATION.md) for commands and limits. These guides are currently in Chinese.
+
+## Portable Core Skill
+
+The package includes `iris-core`, with English instructions and bilingual titles for image import, generation, editing, task inspection, and artifact export through the standalone CLI.
+
+```bash
+dsh-iris skills install --target kimi --dry-run
+dsh-iris skills install --target kimi
+dsh-iris skills status --target kimi
+```
+
+Other harnesses can use an explicit absolute scan directory with `--directory`. Installation copies the complete Skill, records its version and content hashes, and preserves local changes. Managed upgrades and `skills uninstall` archive the previous copy outside the scan root. There is no npm postinstall hook or automatic model/MCP configuration.
+
+The original three DSH Skills remain registered as before. Successful file installation is separate from harness discovery and actual agent behavior; the status command reports `discovery: not_checked`. See [Core Skill installation](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/CORE_SKILLS.md).
+
+## Install and upgrade
+
+For a supported DSH host:
+
+```bash
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.7
+```
+
+For the standalone CLI:
+
+```bash
+npm install @mokuyoaxis/dsh-iris@0.2.7
+npx dsh-iris --help
+```
+
+Back up private Iris data before upgrading. Reload the DSH server code and refresh the client; use your actual profile name instead of `web`. This release does not automatically reload services, migrate existing roots, enable empty model assignments, or change dependency requirements. See the [compatibility matrix](https://github.com/mokuyoaxis/dsh-iris/blob/v0.2.7/docs/DSH_COMPATIBILITY.md).
+
+Use a new, dedicated root for workflow features and local creation. Older writers must not write that root; retain a pre-upgrade backup for rollback. One physical data root still permits one writer, and uncertain acceptance never permits automatic resubmission.
+
+## Scope and verification limits
+
+The source-only standalone Web demo remains an interaction reference for 0.3.0. It uses in-memory samples, does not call models, and is not connected to the local API. It is excluded from the npm package. A production standalone workbench, general Recipe engine, public Core SDK, and formal MCP server are not included.
+
+Validation covers isolated task/artifact behavior, host service integration, package execution, Skill conflict/backup handling, concurrent installers, and actual Kimi Code 2.3.0 Skill discovery/removal. Skill discovery checks submit no prompt and make no model calls; they do not establish a production Kimi adapter. Complete Android interaction, daily hot upgrades, real-provider availability, and whole-data upgrades from Iris 0.1.4 require separate validation. Historical local test-process timeouts remain under investigation.
+
+## 中文摘要
+
+0.2.7 修复浏览器截图保存目录限制、实际导航地址与取消处理，增加主动截图自检；Core/DSH 的写队列和观察器归实例持有。独立 CLI 新增持久图片流程，显式本地 API 默认只读，新空根可主动开启上传与流程创建；这些 HTTP 入口不执行生成。随包 `iris-core` Skill 可显式安装到 Kimi 或指定目录，保护用户修改并保留升级/卸载备份。DSH 原三项 Skill、12 个准确宿主版本与生产依赖保持。独立 Web 仍是面向 0.3.0 的源码演示，正式 MCP 和真实执行工作台继续后续开发。