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

package/docs/IMAGE_GENERATION.md

@@ -0,0 +1,127 @@
+# Core 文生图与 ComfyUI（0.3 beta）
+
+当前源码支持固定 `image-generate/v0`：无需原图，使用明确的 `provider::model` 和提示词生成一张图片。它与改图共用 Run、Operation、Task、作品、原 Key 恢复和有限执行；生成结果无需像素比较，明确选择后可下载或用作下一次改图的原图。**npm 0.2.7 不包含本页的新流程、页面或 MCP 入口。**
+
+## 新建支持文生图的工作区
+
+在新的专用位置初始化 v2 执行根；不要转换现有数据根：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/new-image-core
+node bin/dsh-iris.js execution init --data-root /absolute/new-image-core --image-generation
+node bin/dsh-iris.js web serve --data-root /absolute/new-image-core \
+  --provider-config /absolute/private-providers.json \
+  --token-file /absolute/new-owner-token \
+  --allow-execution --allow-selection --allow-provider-management
+```
+
+v2 可同时保存文生图和改图。原 v0/v1 根继续支持原编辑行为，不自动升级、迁移或开启新功能；旧写者拒绝 v2。连接凭据与恢复身份仍绑定各自的 rootId。
+
+在创作设置选择“生成图片”，明确选择模型、填写画面描述，再点击“开始生成”。创建和执行各使用独立 Key，双击合并；创建结果未知时先找回原 Run，不自动开始生成。修改已有输入需新建流程。
+
+CLI 也可创建同一流程，创建本身不调用模型：
+
+```bash
+node bin/dsh-iris.js flow create --data-root /absolute/new-image-core \
+  --provider-config /absolute/private-providers.json \
+  --input '{"model_ref":"my-provider::my-model","prompt":"A violet iris in soft morning light","n":1}'
+node bin/dsh-iris.js flow continue run_REPLACE_WITH_RETURNED_ID \
+  --data-root /absolute/new-image-core --provider-config /absolute/private-providers.json
+```
+
+`run_REPLACE_WITH_RETURNED_ID` 须替换为创建实际返回的 Run ID。后续继续、选择和导出见 [图片流程](IMAGE_FLOW.md)。已有 Task 有 Attempt 时只处理原任务；受理未知不重新提交。异步任务每次“查看原任务”只观察一次；“停止等待”不等于远端取消或停止计费。
+
+## ComfyUI 入口
+
+需要你已运行的 ComfyUI HTTP 服务和一份能在该服务上执行的 API 工作流。Iris 不安装 ComfyUI、模型或自定义节点，不启动 GPU 服务；独立网页不嵌入节点编辑器。
+
+1. 供应商页选择“ComfyUI · 已有服务”，填写 Iris Core 能访问的地址；本机通常是 `http://127.0.0.1:8188`。远程 Core 的这个地址指向 Core 所在机器。原生 ComfyUI 可选无需认证，受保护的反向代理可使用 API Key/Bearer；不提供 Comfy Cloud/OAuth 登录适配。
+2. 在 ComfyUI 使用 **Export (API)** 导出。展开“ComfyUI 工作流”，导入 API 图或完整 Iris v0/v1 模板，最多 40 KiB、256 个节点；参数声明也计入模板大小。普通画布格式不能直接执行。
+3. 填写稳定的工作流名称，明确正向提示词节点（替换其 `inputs.text`）、图片输出节点和可选尺寸节点（替换 `inputs.width/height`）。展开“开放参数”，勾选已有标量输入、命名并选择整数/小数类型；右侧设置区提供使用时的表单预览。完整 v1 模板保留原参数 ID、类型、范围、选项和顺序。
+4. 已保存、启用的 ComfyUI 连接可做“只读检查”，不保存草稿、不创建 Task、不入队。点击“加入模型草稿”，同名替换需确认，再“保存设置”。连接地址或密钥尚有编辑时，先保存连接，再重新导入模板检查。
+5. 创作页选择此工作流，填写提示词及开放参数。LoRA 槽位分别显示模型与 CLIP 权重，更多参数默认折叠；“检查参数并读取选项”取得当前服务的候选，超出 256 项时保留手填。检查不会替换当前参数；修改输入或切换工作流使旧检查结论失效。
+6. “开始生成”才提交一次工作流，之后明确查看原任务并取回图片。没有绑定尺寸节点时使用模板尺寸，页面禁用尺寸覆盖。首次 v1 提交前后端重新检查实际参数；服务缺少节点/模型或执行失败时，请结合原 ComfyUI 任务检查。
+
+“打开 ComfyUI”在浏览器新标签打开所填服务地址；它不为远程服务建立代理或转发。工作流可调用节点自己的外部服务，应只导入你了解的流程。原始图配置保存在私有 Provider 文件及其备份中，普通设置读取只显示摘要和绑定，不回显图正文；不要将账号凭据写入图节点。
+
+参数表单按模板声明显示，不添加 LoRA 节点或安装模型；多个 LoRA 需要原图已有多个槽位。只读检查需 owner 与 `--allow-provider-management`，仅执行连接仍可填写已开放的参数并按原权限生成。生成点击时固定本次参数快照，新 v1 表单保存全部开放参数的取值；草稿不写入 sessionStorage，恢复表仍只保存请求身份。结果的“流程详情”显示 Run 中实际记录的参数 ID 与值，不用最新模板默认值补写历史；未记录的输入仍依赖原模板。真实 GPU 出图、节点级进度和推理预览尚未验收或接入。
+
+运行时使用 `/prompt`、`/history/{prompt_id}`、`/queue` 和 `/view`。历史和队列都找不到的原任务标记未知，不重新排队。取图只接受原服务的图片接口，不读取 ComfyUI 机器上的任意文件路径。工作流摘要进入原 Task 连接绑定；更改工作流后旧任务不会悄悄改用新图恢复。首版不调用共享服务的全局 `/interrupt`。
+
+协议依据：[官方路由](https://docs.comfy.org/development/comfyui-server/comms_routes)、[API 工作流示例](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/basic_api_example.py)、[原任务与取图示例](https://github.com/Comfy-Org/ComfyUI/blob/master/script_examples/websockets_api_example.py)。Iris 仅接入 HTTP 协议，不随包分发 ComfyUI 或其运行依赖。
+
+2026-10-26 已在线复核官网及官方源码提交 [`fe298e4`](https://github.com/Comfy-Org/ComfyUI/tree/fe298e4e20f1ff26d30e8639267bbd0b57811390)。以下是当前适配边界，源码核对与受控测试不代替真实 GPU 验收：
+
+- [`POST /prompt`](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/server.py#L1164) 会验证并入队，不是只读验证接口。Iris 的只读检查只 GET 节点定义；实际生成才提交一次，并以返回的任务 ID 查询历史/队列，取图沿用官方的文件名、子目录和类型参数。
+- [LoRA 官方定义](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/nodes.py#L714)分别提供模型与 CLIP 权重，多个 LoRA 依靠已有节点串联。候选来自服务端节点定义；Iris 不直接扫描模型目录。
+- 官方当前支持[带任务 ID 的中断](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/server.py#L1262)，但 Iris 首版尚未接入，仍不发送远端 `/interrupt`；停止等待不表示远端已取消。
+- 官方[采样器种子](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/nodes.py#L1606)支持 unsigned 64-bit；Iris 的整数输入限于 JavaScript 安全范围。API 图中直接填写的越界整数也会拒绝，请将种子调至 `0`–`9007199254740991` 后重新导出，避免静默舍入。
+- Iris 提交整份图，只导入所选输出节点的一张图片；其他输出节点或图内外部服务仍可能执行。[SaveImage](https://github.com/Comfy-Org/ComfyUI/blob/fe298e4e20f1ff26d30e8639267bbd0b57811390/nodes.py#L1669)默认可把图与提示词写入 PNG 元数据，Iris 保留原字节，不自动移除这些元数据。
+
+## DSH 工作台入口（0.3 alpha）
+
+当前源码另在原 DSH 工作台中提供专用区域；**npm 0.2.7 尚不包含以下 ComfyUI 界面**。它使用 DSH 侧原配置和 Core Task，不要求另起独立 Core 服务或创建 v2 Flow 根，也不自动接管独立 Core 面板的配置。
+
+1. “设置 → Iris 工作台 → + 添加供应商”，选择“ComfyUI · 已有服务”。默认地址为 `http://127.0.0.1:8188`，按 DSH 进程可访问的地址修改；可选无需认证或 Bearer。保存连接不探测服务、不生成图片。
+2. 在该供应商中导入原始 **Export (API)** 图或完整 Iris v0/v1 模板。明确正向提示词、图片输出和可选尺寸节点；展开“公开参数”，勾选已有标量输入。LoRA 名称、模型权重、CLIP 权重可以分别公开；节点连接不可勾选。普通画布 JSON 不支持。
+3. “只读检查”仅查询已保存服务的节点定义，不保存草稿、不创建 Task、不入队。修正问题后点击“保存工作流”；同名替换另行确认，原摘要不符时拒绝覆盖。保留原 JSON，后续修改模板需再次导入。
+4. 可明确勾选“保存时将图片功能设为自动池”；首次空配置默认勾选，已有功能池保持原选择。未启用时，到“功能池与调用方式”纳入此工作流。
+5. 展开“创作工具 → 画图”，选择具体工作流，再展开默认收起的“工作流参数”。“只读检查并读取选项”可取得服务当前公布的 LoRA、采样器等候选；超出 256 项时可手填名称。多个 LoRA 依赖原图已有节点，不会自动插入或安装模型。
+6. 点击“生成图片”才创建生成 Task。请求前重新核对模板摘要；v1 模板还检查实际参数的节点定义。参数改变会清除旧检查结论，切换模型会清空本卡片的参数覆盖。提交结果未知时先查任务列表，不自动重试或改用另一模型。
+
+地址与认证收在默认折叠的“连接设置”，外观跟随 DSH；进入 ComfyUI 区域有一次短暂鸢尾扫光，遵循减少动画设置。工作台和泡泡常用卡片复用同一画图控件。能力健康中的 ComfyUI 实测转到画图表单，实际生成保留受理/观察/作品事实；静态检查通过不表示真实 GPU 出图通过。
+
+## ComfyUI 参数模板与只读检查（后端）
+
+当前后端支持 `comfyWorkflow.version: 1`，在已有 `graph`、`promptNode`、`outputNode` 和可选 `sizeNode` 上增加明确的 `parameters`。原 v0 模板保持；Core 与 DSH 工作台均支持导入、声明及填写参数。没有开放参数时仍保存 v0 固定模板；v1 完整模板也可通过 CLI `providers add/set` 的 `models[].comfyWorkflow` 保存。
+
+例如，已有图中的 `10` 是 LoRA 节点、`7` 是负面提示词节点、`3` 是采样器，可声明下列参数。此片段只是参数声明，须与原 API 图和输入输出绑定一起保存：
+
+```json
+{
+  "parameters": [
+    {"id":"lora","label":"LoRA","node":"10","input":"lora_name","type":"string"},
+    {"id":"model_weight","node":"10","input":"strength_model","type":"number","min":-2,"max":2},
+    {"id":"clip_weight","node":"10","input":"strength_clip","type":"number","min":-2,"max":2},
+    {"id":"negative","node":"7","input":"text","type":"string"},
+    {"id":"seed","node":"3","input":"seed","type":"integer","min":0},
+    {"id":"steps","node":"3","input":"steps","type":"integer","min":1,"max":100}
+  ]
+}
+```
+
+最多开放 32 个已有标量输入，类型为 `string`、`integer`、`number`、`boolean`，可加数值 `min/max` 或有限 `choices`；默认值来自图，且必须符合声明。参数 ID 和目标不能重复，不能覆盖已绑定的正向提示词或尺寸，也不能替换节点连接。LoRA 模型权重和 CLIP 权重分别声明；多个 LoRA 可使用图中不同节点的不同槽位。整数限制在 JavaScript 安全整数范围，不支持完整 unsigned 64-bit seed。
+
+先做一次只读检查，可提供准备使用的参数：
+
+```bash
+node bin/dsh-iris.js models workflow-check comfy::portrait \
+  --provider-config /absolute/private-providers.json \
+  --input '{"workflow_parameters":{"lora":"portrait.safetensors","model_weight":0.7,"clip_weight":0.4,"seed":42}}'
+```
+
+检查只 GET 官方 `/object_info/{node_class}`，每类查询一次，整体默认限时 15 秒。它报告缺失节点、必需输入、可判断的连接引用/类型、标量范围和枚举，包括节点公布的 checkpoint/LoRA 文件名。结果的 `ok` 仅表示这些静态条件满足；不执行节点、自定义校验或推理，不验证模型家族、显存与外部服务，不证明真实出图成功。参数的 `value` 是本次检查值；模型目录中的 `default` 仍是原模板默认值。候选参数选项最多返回 256 个，超出会标记截断；不扫描磁盘或安装模型。`ok:false` 的业务检查结果仍作为 JSON 正常返回，应读取 `ok/issues`。
+
+v1 模板在每次首次提交前重新检查实际参数与尺寸，检查失败或检查网络中断属于未受理，不发送 `/prompt`；真正 POST 入队后的响应丢失仍保守记为受理未知。v0 固定模板沿用原提交行为，可主动运行上述只读检查。
+
+用 CLI 创建带参数的持久流程：
+
+```bash
+node bin/dsh-iris.js flow create --data-root /absolute/new-image-core \
+  --provider-config /absolute/private-providers.json \
+  --input '{"model_ref":"comfy::portrait","prompt":"An iris portrait","n":1,"workflow_parameters":{"lora":"portrait.safetensors","model_weight":0.7,"clip_weight":0.4,"negative":"","seed":42}}'
+```
+
+HTTP `POST /api/v0/generations` 和 MCP `iris_core_create_generation` 使用可选 `workflowParameters` 对象；`iris_core_models` 返回已明确开放的参数描述。配置检查需 owner 与 `--allow-provider-management`，通过 `POST /api/v0/provider-management/workflow-check` 发送 `{expectedRevision,modelRef,workflowParameters?}`。未保存的模板可改用 `{expectedRevision,providerId,comfyWorkflow,workflowParameters?}`，仅访问已保存且启用的 ComfyUI 连接，不接受临时地址或凭据；两种选择不能混用。检查不写配置或创建 Task，配置在检查期间变化会拒绝旧结果。普通目录读取仍只列已配置工作流。
+
+单次参数最多 24 KiB，参数化 CLI 输入最多 96 KiB；HTTP 正文仍最多 64 KiB。参数会排序并纳入创建 Key 和 Run 输入摘要；同 Key 不同值冲突，同值不同键顺序可重放。带参数 Run 使用记录版本 2，旧读取者拒绝；无参数 Run、原固定模板和摘要保持，已有根不迁移。这里保存的是请求参数和模板绑定摘要，不保存另一份完整图；原模板改变后仍按原规则拒绝将旧任务重新绑定到新模板，并清除该图片模型的过期实测标记。原 Task 的远端查询不重新检查节点目录或生成。
+
+## MCP 能力选择
+
+连接中心的图片组分别选择“生成图片”和“修改图片”；CLI 对应 `image-generate`、`image-edit`，可逗号组合。文生图新增 `iris_core_create_generation`，参数为原请求 UUID、明确模型、提示词、可选尺寸及明确开放的 ComfyUI `workflowParameters`；创建后通过共享的 `iris_core_continue` 明确执行。
+
+只选择文生图时不注册导入/改图创建工具。原连接默认仍为 image-edit 和原 12 工具，不自动增加能力；两个功能都选且具备全部操作权限时共 13 工具。继续、Run/Operation 和已绑定作品读取都核对流程所属能力；这不是同一用户不同连接之间的租户隔离。配置与传输见 [通用 MCP](MCP.md)。
+
+## 验证范围
+
+定向验证覆盖根版本、稳定步骤/Task、重复 Key、未知受理不重提、原结果恢复、选择/下载、MCP stdio/HTTP 授权和真实 Chromium 操作。ComfyUI HTTP 服务响应为受控夹具，未进行真实 GPU/节点/模型出图验收；没有调用付费媒体。实际服务、反向代理与自定义节点仍需在你的部署上验证。

package/docs/LOCAL_API.md

@@ -1,8 +1,10 @@
 # 只读本地 API（0.2.7 / I4A）
 
-0.2.7 增加显式启动的本地 HTTP 入口，默认只提供 GET/HEAD，用来验证无 DSH 环境下的流程查询与图片访问。另有主动启用的 [本地上传与创建](LOCAL_CREATION.md)；继续、选择和取消等执行接口尚未开放。安装包不会自动启动本服务。
+0.3 beta另有 [Core 有限执行与 harness 服务](CORE_SERVICE.md)和 [owner 持久选择](LOCAL_SELECTION.md)，需独立显式开启。本文其余内容说明已发布 0.2.7 的默认只读与零生成创建范围；执行实现及连接协议以上述指南为准。[真实 Web](LOCAL_WEB.md)已按权限接入固定图片创作、选择及连接管理，默认仍只读。
 
-现有 [Web Demo](WEB_PROTOTYPE.md)继续保留为面向 0.3.0 的交互说明，尚未连接这个 API；界面和交互细节到 0.3.0 阶段统一润色。[完整 API 契约](LOCAL_API_CONTRACT.md)中的执行与 Operation 部分仍是设计稿。
+0.2.7 增加显式启动的本地 HTTP 入口，默认只提供 GET/HEAD，用来验证无 DSH 环境下的流程查询与图片访问。另有主动启用的 [本地上传与创建](LOCAL_CREATION.md)；0.2.7 不含继续、选择和取消接口，开发源码的对应入口见上方指南。安装包不会自动启动本服务。
+
+现有 [Web Demo](WEB_PROTOTYPE.md)继续保留为面向 0.3.0 的交互说明，尚未连接这个 API；界面和交互细节到 0.3.0 阶段统一润色。[完整 API 契约](LOCAL_API_CONTRACT.md)分别说明稳定0.2.7能力和0.3 beta的执行、选择实现。
 
 ## 显式启动与停止
 

package/docs/LOCAL_API_CONTRACT.md

@@ -1,12 +1,22 @@
 # 独立本地 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 分发。
+0.2.7实现 **I4A 默认只读**与 **I4B 显式本地创建**：显式本机监听、Bearer/Host/Origin、受控流程/媒体，以及主动启用的上传/创建与持久身份接回，见 [只读 API](LOCAL_API.md)和 [本地创建](LOCAL_CREATION.md)。0.3.0-alpha.1另提供 [有限执行服务](CORE_SERVICE.md)、[连接握手](CORE_CONNECTIONS.md)与 [owner持久选择](LOCAL_SELECTION.md)。本契约尚未冻结为公开SDK；稳定0.2.7只包含上述I4A/I4B入口。
 
-当前固定流程的真实执行入口仍是 [CLI](IMAGE_FLOW.md)；[独立 Web Demo](WEB_PROTOTYPE.md)只消费内存演示，保留到 0.3.0 阶段统一润色。它尚未接入只读 API，也不作为完整服务或写操作已经实现的依据。
+已发布固定流程通过 [CLI](IMAGE_FLOW.md)执行，0.3 beta另有上方 Core 服务；[独立 Web Demo](WEB_PROTOTYPE.md)只消费内存演示，保留到 0.3.0 阶段统一润色。Demo 尚未接入只读 API，也不作为完整服务或写操作已实现的依据。
+
+0.3 beta另有 [Core 工作台](LOCAL_WEB.md)，通过显式 `web serve` 同源提供固定静态资源；登录页不包含私有数据，API/图片仍要求 Bearer。默认只读，创建、执行和选择分别显式开启，不要求连接管理；页面按能力接入改图、比较、选择、停止和下载。npm 0.2.7 尚不含，不改变下方已发布 I4A/I4B 的能力边界。
+
+源码另实现 [Operation 存储与版本门禁](LOCAL_OPERATIONS.md)，只在新专用根主动初始化；显式 `api serve --allow-execution` 装配 runner、持久接收/查询与本地停止，默认模式与刷新恢复仍只读。v1 根复用零生成创建，写者拒绝损坏记录；具体执行与握手以服务指南为准。
+
+0.3 beta的 [Core 音频流程](AUDIO_FLOWS.md)另在新 v3 根增加 `/audio-models`、`/audio`、`/speeches`、`/transcriptions`、作品 `/audio` 和 `/text`，以及 Run 类别筛选。音频与图片共用原 runner/Task/Key；现有图片 `/content` 保持图片类型限制。播放/下载最多64 MiB音频或1 MiB文本，输入音频最多20 MiB且核对容器/MIME，不接收任意路径/URL。下方 I4A/I4B 表继续描述已发布图片切片，不能据此把音频入口用于旧根。
+
+**beta.1**另在显式新v4根增加[固定文生视频](VIDEO_FLOWS.md)的 `/video-models`、`/videos` 与作品 `/video`，读取MP4/WebM最多32 MiB，先核对metadata再读取；与图片/音频共用原Operation与授权边界，旧根不自动升级。
+
+源码另有 owner 专用只读 `GET/HEAD /api/v0/capabilities`：返回 `contractVersion:0,state,scopeOptions,controlTools,groups,tools,media,plugins,contributions`，装配插件时附 Core 版本及准确贡献依赖。无模型密钥、数据根或可加载脚本路径；无凭据401，连接凭据403，未知查询参数400。此完整目录不表示当前用户授权或媒体健康。连接管理目录复用同一投影并另附 availableScopes/defaults 等服务选项；`session.operations` 由 Core 的 Web 映射和实际根版本、开关、授权交集生成。详情见 [插件目录](PLUGINS.md#core-能力目录与授权)，不改变已发布 I4A/I4B 的契约范围。
 
 ## 1. 实例与启动
 
-一个服务实例显式绑定一个已初始化的专用 Flow 根和一个 Application Runtime。Provider 配置来源可显式提供，省略时仍可查看已有流程/图片，启用本地写入后也可上传；模型列表返回未配置，不能创建新 Run。由用户主动启动，固定仅监听 `127.0.0.1`；首次不支持远程监听、代理转发或自动扫描 DSH 配置。CLI 的 `flow init` 仍负责初始化新根，浏览器不能指定根路径、初始化旧根或变更 Provider 配置。
+一个服务实例显式绑定一个已初始化的专用 Flow 根和一个 Application Runtime。Provider 配置来源可显式提供，省略时仍可查看已有流程/图片，启用本地写入后也可上传；模型列表返回未配置，不能创建新 Run。由用户主动启动，固定仅监听 `127.0.0.1`；首次不支持远程监听、代理转发或自动扫描 DSH 配置。CLI 的 `flow init` 仍负责初始化新根，浏览器不能指定根路径或初始化旧根。beta.1 C3 另以独立开关提供 owner 供应商管理，只操作启动时固定的配置，见 [管理契约](PROVIDER_SETTINGS.md)。
 
 API 使用 `/api/v0` 前缀，后续静态页面须与 API 同源。只有 HTTP 适配器负责验证外部输入、生成受控 DTO 和管理请求；不得把 `application.execute(name, input)`、现有 DSH `serveApi` 或 CLI 参数作为通用 HTTP 转发口。模型来自显式配置中允许改图的候选，Flow 继续绑定单一明确模型与 `n=1`。
 
@@ -14,9 +24,12 @@ I4B 的上传与 Run 创建均不生成，完成本地提交后返回 201，同
 
 ## 2. 身份与浏览器边界
 
-- 每次启动产生 32 字节随机会话 Token，CLI 通过必填 `--token-file` 写入新的根外私有文件（POSIX 0600），不打印 Token。服务鉴权使用 Token 摘要和等时比较；调用进程读取私有文件，以 `Authorization: Bearer …` 发送，不进入 URL、命令行参数、Run、日志或错误文本。未来浏览器只在标签页内存保留 Token；页面重新连接不开始生成。首版文件交付替代最初的终端显示提案，支持自动化且避免管道日志收集 Token。
-- **所有 API，包括模型列表、状态与媒体，都验证身份**；Token 比较使用等时比较。首版不使用 Cookie，也不建立“同源就已认证”的假设。退出页面丢弃客户端 Token；停机使该进程 Token 失效。
+- `api serve` 每次启动产生32字节随机 owner Token，CLI 通过 `--token-file` 或 `--token-dir` 写入新的根外私有文件（POSIX0600），不打印 Token。服务鉴权使用摘要和等时比较；调用进程读取私有文件，以 `Authorization: Bearer …` 发送，不进入 URL、命令行参数、Run、日志或错误文本。普通 `web serve` 改由根外私有认证存储管理口令与浏览器会话；记住设备时浏览器独立凭据保存在 origin 隔离的 localStorage，普通模式用 sessionStorage，不保存口令或 owner/MCP 密钥。刷新先 GET 验证，不开始生成，见[工作台登录](WORKBENCH_LOGIN.md)。
+- 模型列表、业务状态、媒体与管理 API 均要求 Bearer 身份；owner Token 使用摘要及等时比较。不使用 Cookie，也不建立“同源就已认证”的假设。工作台主动退出经服务确认后撤销当前浏览器会话，401清除失效的客户端登录；口令模式的有效浏览器会话跨正常重启保留，进程 owner 控制令牌仍轮换。
+- 普通 `web serve` 的有限登录入口为 `GET/HEAD /api/v0/workbench/auth`、严格同源 `POST /setup`、`POST /password-login`、`POST /logout`（后三者均在 `/api/v0/workbench` 下），字段和权限见[口令接口](WORKBENCH_LOGIN.md#接口与装配)。首次设置要求启动器交付的随机片段票据，没有10分钟窗口，成功后失效。`POST /setup-link` 与 `/password-reset` 只接受本机 owner 控制令牌，浏览器及 MCP 凭据不可调用。
+- 显式 `--token-file` / `--token-dir` 的旧工作台模式保留 `POST /api/v0/workbench/login`、`/login-link` 和10分钟一次性链接；票据与浏览器身份仅在进程内保留摘要，服务重启失效。口令模式拒绝这两个旧接口。`api serve` 不开放工作台登录入口，MCP仍使用连接专属凭据。
 - `Host` 必须精确匹配实际监听 authority。带 `Origin` 的请求仅允许该页面精确 origin；`Origin: null`、外站 origin 和不匹配 Host 拒绝，不采信 `Forwarded` 或 `X-Forwarded-*`。无 Origin 的本机 CLI 请求仍须通过 Host 与 Token 检查。不同 origin 的 OPTIONS 不开放 CORS。
+- 公开工作台首页允许外站顶层GET导航，以便直接点击登录链接；必须是document/navigate，不把此例外用于iframe、脚本、外站fetch或业务API，Host和已有Origin检查仍保留。
 - 当前 API 响应使用限制性 CSP。未来页面的脚本/样式只从本站加载，无内联脚本、第三方资源、对象、框架嵌入或表单提交；用户内容用文本节点展示，媒体通过带认证的 fetch 获取 Blob 后展示/下载，不将 Token 放入 `<img>` URL。
 - JSON、状态、媒体和错误响应使用 `Cache-Control: no-store`、`X-Content-Type-Options: nosniff`；API 不重定向到 Provider URL。首切片仅为意外服务错误记录净化调用帧与关联 ID。若增加访问日志，只记录方法、固定路由类型、状态、随机关联 ID 与耗时，不记录 Authorization、正文、查询参数或绝对路径。
 
@@ -24,26 +37,40 @@ Bearer、Host/Origin 与 CSP 是不同边界，不能相互替代。静态预览
 
 ## 3. 有限路由
 
-下列除 Operation 外的 GET 路由已实现，并支持同样鉴权的 HEAD；I4B 只实现 images/runs 两个 POST，其他 POST 与 Operation 查询仍是提案。JSON 响应含 `contractVersion: 0`；列表最多 30 项，摘要不含 Prompt；创建 JSON 上限 64 KiB，Prompt 使用现行生成输入约束。未知/重复查询参数和带正文的只读请求拒绝。
+实验性公开插件工作台可通过 `allowedOperations` 开启持久 `plugin.execute`；媒体执行仍独立开关。它增加以下有限路由，逐请求核对 scope/tools/准确依赖，插件处理器只能调用已声明的 Core 子集；不是通用命令转发。
 
 | 方法与路径 | 输入 | 语义 |
 |---|---|---|
-| `GET /session` | 无 | 返回实例标识、契约版本、允许的操作与输入上限；不返回根路径、Key 或端点 |
+| `GET /plugin-operations/catalog` | `offset`、`limit=1..30` | 当前连接选择的业务、准确依赖、输入 Schema、available及现有图片；分页沿用作品库 offset/total，过滤不支持类型及超过8 MiB的图片，nextOffset用于继续读取 |
+| `POST /plugin-operations` | UUIDv4 `Idempotency-Key`，`{operationId,dependency,input}`，正文最多64 KiB | 202持久回执；同 Key 同输入读原记录，变更冲突。需要 execute和plugin_call，接受及Core命令处检查有效授权 |
+| `GET /plugin-operations` | `limit=1..30`、`cursor` | 按当前准确业务选择过滤后分页的持久历史；owner可读全部，不要求插件实现仍安装 |
+| `GET /operations/:id`、`GET /operations?key=…`、`POST /operations/:id/cancel` | 原 ID/UUID；cancel正文 `{}` | 复用原查询/接回/本地停止，按记录的准确依赖鉴权；新业务结果含Core确认的artifactIds |
+
+会话附 `pluginExecution/pluginOperations` 和允许的 plugins.catalog/plugins.execute 等别名。工作台有内建业务记录页，插件缺失仍可查原作品。启动将遗留在途记录标为 interrupted，不自动重做；业务 succeeded 仅表示处理器返回及Core命令完成。详见[真实业务](CONTACT_SHEET.md)。
+
+下列 GET/HEAD 已有实现，Operation 路由需beta.1的显式执行模式；I4B 只含 images/runs 两个 POST，执行模式另含 continue/cancel，selection 需独立 `--allow-selection` 且仅限 owner。JSON 响应含 `contractVersion: 0`；列表最多 30 项，摘要不含 Prompt；创建 JSON 上限 64 KiB，执行/选择/连接 JSON 上限 8 KiB。未知/重复查询参数和带正文的只读请求拒绝。
+
+| 方法与路径 | 输入 | 语义 |
+|---|---|---|
+| `GET /session` | 无 | 返回实例标识、契约版本、允许的操作与输入上限；owner 会话另有稳定 rootId（无请求区为 null），默认 Panel 显式选中扩展时附 panelContributions（身份、准确依赖、本站资源 URL）；连接凭据不获此清单，不返回根路径、Key 或端点 |
+| `GET /creation-requests`（0.3 beta） | `kind=image-import/flow-create`、原 UUIDv4 `key` | 仅 owner；默认只读也可核对已有请求，返回 kind/state 与经核验的结果引用或 null，不补写或生成 |
 | `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；只读，不观察远端 |
+| `GET /runs` | `cursor`、`limit`，limit 1–30；0.3 beta另有 `selection=all/selected/unselected` | 已有流程摘要，不含 Prompt；只读，不观察远端。先按选择筛选再计算 total/分页，另有 counts 全部/已选/未选计数 |
 | `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 的原图/新版；不触发生成或下载 |
+| `POST /runs/:id/continue`（0.3 beta执行模式） | `{expectedRevision}`、Idempotency-Key | 持久接收后 202，同 Key 200；一次首次提交/观察/补交付/比较，不重提已有 Attempt |
+| `POST /runs/:id/selection`（0.3 beta选择模式） | `{artifactId, expectedRevision}` | 仅 owner；同 writer 核对版本并保存原图/结果选择，返回 200；过期版本 409，不触发生成或下载 |
 | `GET /artifacts/:id/content` | 无 | 按已验证 Artifact ID 和清单读取该根内媒体字节，不接受 path/URL 参数；不写文件 |
 | `GET /runs/:id/download` | 无 | 返回已选择图片的原字节及受控附件名；未选择则冲突，不接受服务器输出路径 |
-| `GET /operations/:id`（待实现） | 无 | 查询本实例操作状态，不能借此继续操作 |
-| `POST /operations/:id/cancel` | 空 JSON | 停止本次排队/等待，幂等；不代表远端生成已撤销或已退款 |
+| `GET /operations/:id`（0.3 beta执行模式） | 无 | 查询持久状态，不能借此继续操作；原 Key 查询和 Run 列表见服务指南 |
+| `POST /operations/:id/cancel`（0.3 beta执行模式） | 空 JSON | 原 ID 幂等停止本地排队/等待，终态落盘后 200；不代表远端已取消或已退款 |
 
 上传累积读取限制使用现有 `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 事实。
+上传复用现有图片验证与 Artifact 预留 ID 提交；请求与作品在同一次 writer 内保存。上述I4A/I4B图片读取/下载限64 MiB，类型PNG/JPEG/WebP，先检查清单大小再校验内容哈希，最多两个活动读取。当前独立API的媒体入口仍采用有限整读、不支持Range；新增音频与beta.1视频入口分别见上方说明。DSH媒体路由的流式发送与这个独立API分开实现。下载不调用服务器本地 `flow.export(output_path)`；浏览器是否保存成功不属于持久 Run 事实。
+
+0.3 beta HTTP列表摘要保留 id/recipe/createdAt/modelRef/source，另投影 updatedAt、revision、output/selection 引用（无值为 null），不附 Prompt、Task、供应商绑定或路径；CLI/MCP 列表保持原语义。省略 selection 等于 all，未知/重复参数或不属于筛选结果的 cursor 返回400。图库封面使用 selection，否则 source。
 
 ## 4. FlowView 与操作反馈
 
@@ -79,7 +106,7 @@ ID 继续使用当前 `run_` / `task_` / `artifact_` 加 24 位小写十六进
 
 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 自动开放。
+0.3 beta执行模式在原子接收后返回 `202 {contractVersion:0, operation, idempotentReplay:false}`；重放返回 200，状态为 `queued | running | succeeded | failed | canceled | interrupted`。GET 不驱动 Provider；每次显式继续至多一次观察。单根最多 8 条 queued/running，同 Run 最多一条；writer 忙时拒绝新接收，不声称已排队。停止直接中止控制器，随后在同 writer 下落盘并返回 200；不伪造远端 Task canceled。此模式不随 I4B 或只读 Web 自动开启。
 
 ## 5. 上传与持久创建幂等（I4B）
 
@@ -96,7 +123,7 @@ I2 保证相同 Run 使用原 Task；I4B 另保证同 Key 创建请求接回原
 7. 新版 writer 和维护入口必须识别请求格式，未知/半初始化请求区拒绝写入。已发布旧程序没有这些新检查，不能靠一个标记保证其拒绝该根；此专用根只支持已验收的 request-aware writer，回退使用完整副本，不删除请求区伪装降级。已提交 Flow/图片仍可只读查看。
 8. 复用现有原子发布和重入能力，验证范围限进程异常退出/SIGKILL；不据此承诺断电、操作系统崩溃或共享存储下的跨文件事务。请求区本身不触发 Provider 目录刷新、探测、生成或任务观察。
 
-后续 continue/Operation 仍需独立的持久接收与中断协议；重启只展示未完成事实，**不能自动重放 continue**。I4B 的本地创建与中断证据不能代替可能计费的执行验收；开始按钮接入实际生成前，仍须补执行接收、未知受理、取消和停机测试。
+0.3 beta continue/Operation 使用独立 runner 与持久身份，显式启动只记录遗留中断，**不能自动重放 continue**。I4B 创建证据与执行验收分开；Web 的连接管理写入见 [连接契约](CORE_CONNECTIONS.md)。选择复用 Run 原子提交：当前版本的同目标选择不重写，旧版本即使目标相同也冲突；没有持久 Key/选择收据，响应丢失先 GET 核对，见 [持久选择](LOCAL_SELECTION.md)。源码已实现 [原创建 Key 查询、稳定根身份及浏览器恢复](WEB_RECOVERY.md)和真实创作按钮；刷新或找回创建成功均不自动首次执行。
 
 ## 6. 错误与验收
 

package/docs/LOCAL_CREATION.md

@@ -1,5 +1,9 @@
 # 本地上传与流程创建（0.2.7 / I4B）
 
+0.3 beta另支持 [Operation 执行根](LOCAL_OPERATIONS.md)与 [Core 有限执行服务](CORE_SERVICE.md)，需在新空 Flow 根显式 `execution init`，执行另主动开启；上传/创建仍不生成。下文说明已发布 0.2.7 的 v0 初始化流程，各种根不自动转换。
+
+新的 `execution init --image-generation` 使用 v2 容器；owner 可通过 POST `/api/v0/generations` 保存 `{modelRef,prompt,size?,workflowParameters?}`，使用独立的 `generation-create` 原 Key 查询与重放，不接受来源图片。`workflowParameters` 仅用于明确开放槽位的 ComfyUI 模板，并纳入原 Key 和 Run 输入摘要；旧 `/runs` 不接受该字段。旧 `/runs` 创建仍必须提供来源，不能借旧编辑工具调用新能力。见 [独立文生图](IMAGE_GENERATION.md)。
+
 0.2.7 在 [只读本地 API](LOCAL_API.md)之上，增加显式启用的图片上传和固定 Run 创建。两者都只提交本地数据，不生成、不观察任务、不调用 Provider。实际生成仍使用 [Flow CLI](IMAGE_FLOW.md)；执行/取消 API 与真实 Web 接入留到后续。本功能从 npm 0.2.7 起随包分发。
 
 ## 初始化与启用
@@ -31,10 +35,12 @@ dsh-iris api serve --data-root /absolute/path/new-flow-core --token-file /absolu
 
 超限返回 `413 IRIS_API_INPUT_TOO_LARGE`，不创建作品或消费 Key。对尚未结束的上传，先发送完整错误响应，再丢弃剩余正文并关闭连接；不继续缓存正文，连接仍受现有请求/空闲超时和服务停止约束。客户端收到拒绝后应停止上传。
 
-当前没有 `POST /runs/:id/continue`、selection、Operation 查询或取消接口。GET、HEAD、页面刷新和启动不自动执行或补完创建；现有 Demo 仍使用演示传输，尚未连接这个 API。
+已发布 0.2.7 与仅开启 `--allow-local-writes` 时没有 continue、selection、Operation 查询或取消接口。GET、HEAD、页面刷新和启动不自动执行或补完创建；现有 Demo 仍使用演示传输，尚未连接这个 API。
 
 ## 重试、删除与中断
 
+0.3 beta增加 owner-only 的原 Key 只读查询和 session 稳定 rootId，v0/v1 请求区均可读取；prepared 不自动补完，默认只读服务也不创建请求区。浏览器刷新先验证标签页保存的登录，再 GET 核对，详见 [工作台请求恢复](WEB_RECOVERY.md)。此查询不在已发布 npm 0.2.7 中。
+
 请求意图、预留身份、业务提交和完成状态共用同一次 Core writer。跨进程重启、端口变化或 Token 轮换后，同 Key 仍绑定原数据根和原输入；已有 Run 后续执行或选择过，重放返回其当前 FlowView，不回退进度。已有意图不因当前 Provider 配置变化另选模型/端点，未来执行仍遵守原 Flow binding。
 
 意图发布前的输入错误、busy、排队取消或断线不消费 Key；发布后断线不撤销本地提交。未完成上传需要重新提供相同字节；显式同 Key POST 才核对或补完，没有自动后台重放。关闭服务会停止接收和等待，并保留未完成证据。

package/docs/LOCAL_OPERATIONS.md

@@ -0,0 +1,46 @@
+# Operation 存储与版本门禁（0.3 beta）
+
+持久 Operation 记录一次明确有限调用的意图、原身份和状态。原 `flow.continue` 继续媒体 Run，新增 `plugin.execute` 执行明确选中的真实业务；共用单根 runner、队列、租约、HTTP 202/原 Key 接回和本地停止。默认 API 仍只读；主动开启方式见 [Core 执行服务](CORE_SERVICE.md)及[多图对照板](CONTACT_SHEET.md)。原 CLI 图片流程保持。
+
+Operation 表示一次有限调用，Run 表示创作流程，Task/Attempt 表示外部受理与结果。Operation 成功并不等于图片完成；running 是最后保存的本地状态，不证明处理器仍在线。存储 CLI 初始化/查询不执行模型；执行服务启动只标记遗留中断，查询和原 Key 重放不重新生成或观察 Provider。
+
+新增 [文生图](IMAGE_GENERATION.md)使用显式 `execution init --image-generation` 的新 v2 根，runner 和 Operation 语义相同，绑定没有来源/比较作品；首次执行前或停止时作品列表可为空。原 v0/v1 不自动迁移，旧写者拒绝 v2。以下不带开关的初始化仍建立原 v1 编辑执行根。
+
+新增[语音/转写](AUDIO_FLOWS.md)使用显式 `execution init --audio` 新 v3 根，同时支持原图片流程。音频步骤固定为 speak/transcribe，Task、来源和输出的持久绑定仍逐项核对，停止及中断不重提；v0/v1/v2不迁移，旧程序拒绝不支持的请求区版本。
+
+## 显式初始化与查询
+
+以下命令针对0.3 beta；已公开 npm 0.2.7 没有此入口。需要 Node.js ≥22 和项目现有依赖：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/path/to/new-flow-root
+node bin/dsh-iris.js execution init --data-root /absolute/path/to/new-flow-root
+node bin/dsh-iris.js operation list --data-root /absolute/path/to/new-flow-root
+node bin/dsh-iris.js operation inspect op_REPLACE_WITH_64_HEX --data-root /absolute/path/to/new-flow-root
+```
+
+`execution init` 只接受新的空 Flow 根，建立 `creation-requests/v1/`，包括请求记录、Operation、根声明和预留的空 runner 目录。输出 `executionEnabled: false`。重复初始化同版本根接回原声明，不改写业务和请求记录，但仍通过 writer 检查；不会把现有 v0 请求根升级，也不会降级 v1。缺失的 Flow 根、已有作品/流程的普通根和部分初始化均明确拒绝，不自动清理。
+
+没有 CLI 接收/执行 Operation 的命令；终端开放列表与单项查询，支持 `--run-id`、`--limit 1..30`、`--cursor`。媒体记录投影保持。插件业务通过公开工作台持久接收，投影另含准确依赖、JSON输入、输入摘要和来源作品，不含owner或存储路径；输入属于获授权可读的业务数据。
+
+`plugin.execute` 使用有版本的 Operation schema1 分支，原 flow记录/根声明不迁移；旧 Core 遇到未知记录明确拒绝，不承诺降级。输出身份先持久预留，Core 写入后才作为实际作品投影；中断保留已提交部分结果。插件缺失/升级不改变原记录；恢复准确版本也不自动重放。其 succeeded 代表业务处理器及Core命令完成，区别于媒体 Task 完成。
+
+## 身份与状态
+
+- 身份按根 UUID 与小写 UUIDv4 Key 派生为 `op_<64 hex>`，不依赖 Token、端口或进程，原 Key 不单独复制。媒体记录不复制 Prompt；插件记录保存其实际JSON输入并纳入摘要，同 Key 改输入/依赖拒绝。
+- 同 Key、同 Run/revision 接回原记录，包含已结束或取消记录；变更输入复用 Key 拒绝。同 Run 最多一条 queued/running，单根活动上限 8；被拒绝的请求不落盘。
+- 接收写入单条完整记录，不双写索引。状态转换按 Operation revision 检查，允许排队、开始及成功/失败/取消/中断的有限转换，结束记录不重新排队。
+- 存储原语只修改 Operation 文件；真实继续与 Abort 由显式 runner 持有 writer 调用。停止不发远端取消，不改写远端 Task 的已知结果。
+- 单纯查询保留原状态；显式启动执行服务取得所有权后将遗留 queued/running 标记 interrupted，但不执行它们。调用方必须明确核对原 Run/Task。未知受理不因存储重放而重新生成。
+
+记录绑定 Run 的私有输入摘要、预留 Task 和来源/比较作品 ID。完成时保存已有 Run revision 与结果引用，不复制 Provider 配置、完整异常或媒体。错误只记录有限类别。所有记录的引用暂继续保留，归档/释放策略另列，不自动 GC 或清除请求身份。
+
+## 版本与维护
+
+原 `creation-requests/v0` 行为与记录格式保持。v1 中的本地图片上传/Run 创建复用现有零生成逻辑与持久 Key；[只读工作台](LOCAL_WEB.md)仍然只读。
+
+新版写者启动时检查请求容器、Operation 结构和原 Run/Task 绑定。未知版本、损坏记录、混合容器、符号链接或未知 runner 内容会阻止写入并保留现场。新根也由已发布 0.2.7 的真实 CLI 验证拒写；更早版本和任意外部程序不在此保证内，不应把实验根交给它们维护。
+
+删除与清理盘点识别 Operation 的 Task/Artifact 引用，结束记录也继续保护引用；请求/Operation 文件及临时证据不在清理白名单内。旧隔离内容恢复仍遵守当前写者门禁和不覆盖规则。
+
+私有目录/文件创建时采用 0700/0600；Windows 的 mode 不替代 ACL。原子提交和进程强杀验证不等于断电耐久，也不等于 Android 共享存储已经验证。当前无个人数据迁移或公开发行。

package/docs/LOCAL_SELECTION.md

@@ -0,0 +1,57 @@
+# 本地持久选择（0.3 beta）
+
+源码的 `api serve` 和 `web serve` 可显式开放选择接口，将已完成图片流程的原图或生成结果保存为当前作品。**npm 0.2.7 尚不包含此接口**；[真实工作台](LOCAL_WEB.md)已接入原图/结果选择，服务确认后才显示已选状态，冲突或回包丢失时读取当前事实。
+
+## 显式开启
+
+在已有专用 Flow 根上启动；不初始化或转换原根，不需要 Provider 配置，也不要求连接管理、创建或执行模式：
+
+```bash
+node bin/dsh-iris.js web serve --data-root /absolute/path/to/flow-root \
+  --token-file /absolute/path/to/new-owner-token --allow-selection
+```
+
+也可换用 `api serve`。默认不开启；`--allow-local-writes`、`--allow-execution` 和 `--allow-connection-management` 均不会隐式开启选择。创建和执行模式仍各自要求已初始化的请求区或 v1 执行根，见 [本地创建](LOCAL_CREATION.md)与 [Core 服务](CORE_SERVICE.md)。
+
+Token 文件须为根外新文件，权限沿用本地 API 约定。只有本次服务的 owner Token 能调用选择；连接凭据即使拥有全部 MCP 权限也不能调用，不新增 MCP scope 或工具。Bearer、精确 Host、同源 Origin 和禁止跨站请求的检查保持，见 [访问边界](LOCAL_API.md#身份与访问)。
+
+## 请求与版本门禁
+
+先通过 `GET /api/v0/runs/:id` 读取最新 `revision` 与原图/结果的 Artifact ID，再由用户明确选择：
+
+```http
+POST /api/v0/runs/:id/selection
+Authorization: Bearer <owner-token-from-private-file>
+Content-Type: application/json
+
+{"artifactId":"artifact_<24 lowercase hex>","expectedRevision":7}
+```
+
+正文只接受这两个字段；`expectedRevision` 必须是正安全整数，JSON 上限 8 KiB。原图或结果须属于该 Run，且流程已完成比较。路径、URL、比较图和其他 Run 的作品均不能作为选择目标。
+
+版本核对和选择写入在同一个 Application writer 中完成，复用原子 Run 提交，不新建请求区、Operation 或选择收据，也不改 Run 格式。成功返回 `200` 和当前 FlowView：
+
+- 选择改变时，Run 的 `revision` 增加一次。
+- 当前版本重复选择同一作品时，不重写记录、不增加版本。
+- 版本已过期时返回 `409 IRIS_API_RUN_CHANGED`，即使目标恰好与当前选择相同也拒绝，避免旧操作覆盖后来的决定。
+- 本实例有活动或排队写入、runner 操作，或其他写者占根时，返回 `409 IRIS_API_ROOT_BUSY`；不承诺排队。
+
+本接口不提供持久 `Idempotency-Key` 接回。响应丢失后先 GET 当前 Run 核对真实选择；若要改变，使用当前版本再次明确提交，不自动重试旧请求。请求在开始写入前断开会取消未开始项；已经提交的选择保留，不能因客户端未收到响应而回滚。
+
+## 结果与错误
+
+选择不调用 Provider，不创建/观察 Task，不触发生成或下载。之后的 `GET /api/v0/runs/:id/download` 返回已选图片原字节；浏览器保存完成仍以下载记录为准。
+
+| 状态 | 含义 |
+|---|---|
+| 400 / 413 | 字段、类型、版本或请求格式无效 / 正文超限 |
+| 401 / 403 | 身份无效 / 访问边界不符或调用方不是 owner |
+| 404 | 合法 Run ID 不存在 |
+| 405 | 未显式开启选择，或方法不支持 |
+| 409 `IRIS_API_RUN_CHANGED` | Run 版本已改变，先读取再决定 |
+| 409 `IRIS_API_RUN_NOT_READY` | 比较尚未完成 |
+| 409 `IRIS_API_SELECTION_INVALID` | 作品不属于该 Run 可选的原图或结果 |
+| 409 `IRIS_API_ROOT_BUSY` | 写者或执行器忙 |
+| 500 | 意外写入错误；不报告成功，响应只提供净化错误与关联 ID |
+
+CLI 的 `flow select` 保持原有用法；内部应用调用另支持可选 `expected_revision`。页面按钮、创建身份查询与刷新恢复属于后续切片，不因本接口完成而自动具备。