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

package/docs/PLUGIN_STARTUP.md

@@ -0,0 +1,113 @@
+# Core 启动与插件启用（0.3 beta）
+
+仅需媒体创作或首次连接 Agent 时，可先走 [Core 快速开始](CORE_QUICKSTART.md)；本页说明如何额外启用可信插件，不必先编写 Node 启动脚本。
+
+开发自己的独立插件可从[模板与包外验收](PLUGIN_DEVELOPMENT.md)开始；普通用户使用下面的随包入口即可。
+
+使用0.3.0-beta.1或当前源码；**稳定 npm 0.2.7 没有这些插件启动参数。** 本地安装可在下文 `dsh-iris` 前加 `npx`，源码树可替换为 `node bin/dsh-iris.js`。
+
+沿用 `web serve` / `api serve` 启动一个明确数据根的 Core 服务。插件配置只决定加载与启用，不安装插件、不创建 MCP 授权。stdio MCP 启动的是连接此服务的桥接进程，HTTP MCP 使用同一服务的 `/mcp`；两者都需要 Core 继续运行。
+
+## 准备一次，重复启动
+
+选择已经存在的父目录，如 `/absolute/iris`。下面使用新的专用数据根；必须在导入作品前完成执行初始化，不迁移已有根：
+
+```bash
+dsh-iris flow init --data-root /absolute/iris/core
+dsh-iris execution init --data-root /absolute/iris/core
+```
+
+将下面内容保存为 `/absolute/iris/startup.json`，它只启用随包[多图对照板](CONTACT_SHEET.md)：
+
+```json
+{
+  "schemaVersion": 0,
+  "entries": ["builtin:contact-sheet"],
+  "operations": ["community.contact-sheet.create"],
+  "panel": {
+    "pages": ["community.contact-sheet.board"]
+  }
+}
+```
+
+列出随包入口并检查明确选择：
+
+```bash
+dsh-iris plugins list
+dsh-iris plugins inspect --plugin-config /absolute/iris/startup.json
+```
+
+`inspect` 输出实际插件 ID、版本、兼容范围、贡献和启用选择；不启动 Core、不建立执行租约或连接授权。它会导入并激活**可信 Node 代码**，随后释放资源；不是代码沙箱，也不验证供应商、模型或 GPU。
+
+启动工作台、连接管理与 HTTP MCP：
+
+```bash
+dsh-iris web serve --data-root /absolute/iris/core \
+  --plugin-config /absolute/iris/startup.json \
+  --port 3182 \
+  --connection-store /absolute/iris/connections \
+  --allow-connection-management --allow-mcp
+```
+
+首次打开输出的 `loginUrl` 设置访问口令，之后使用普通地址；“记住此设备”可跨刷新与正常重启，退出后输入原口令即可。见[工作台登录](WORKBENCH_LOGIN.md)。对照板使用已有 Core 图片；可在第一次启动前用 `artifact import` 导入，见[完整业务用法](CONTACT_SHEET.md)。它无需 Provider 配置或 `--allow-execution`；后者控制媒体流程，插件业务执行独立选择。
+
+正常 Ctrl+C 退出后，可以原样重复启动命令。保持同一数据根、固定端口、连接目录和所需准确插件版本，已经导出的 MCP 连接继续有效。不要同时启动两个管理同一根的执行服务；冲突会报忙，不抢锁。强制退出后的租约恢复仍须先核对进程，再按 [Core 服务](CORE_SERVICE.md)的明确命令处理。
+
+## 查看插件状态（当前源码）
+
+此页入口从 **0.3.0-beta.1** 提供；登录后打开侧栏“插件”：
+
+- 插件卡片列出准确身份、版本和 Core 兼容范围，展开后查看模型协议、业务操作、页面、设置与预览贡献。加载时通过兼容校验不代表模型或业务已经实测。
+- 业务是否被服务启用、页面是否选入工作台，分别取自 Core 的实际装配；加载代码不等于授权。
+- 客户端授权区分准确版本不一致、服务未启用、缺少执行权限、未选 `plugin_call` 和已撤销；“授权允许执行”只描述配置条件。握手实例可能请求更小的范围，握手记录也不证明客户端持续在线。
+- 原授权所需的业务未加载时保留准确依赖和原因，不会自动改成新版本或移除原记录。授权读取失败显示“未知”，不会冒充零授权；重新读取只访问现有只读接口，不调用业务或探测模型。
+
+“管理客户端授权”打开已有连接设置。此页不编辑启动文件、安装插件或热加载代码；启用仍按下方选择文件，在正常停止后重新启动服务。若启动失败、服务尚未运行，请在启动终端核对 `code`、`stage`、`file` 和可能的 `field`，也可对确认可信的插件运行 `plugins inspect`；页面无法读取一次尚未启动服务的失败。
+
+## 选择文件
+
+| 字段 | 含义 |
+|---|---|
+| `schemaVersion` | 必须为 `0`；不自动迁移 |
+| `entries` | 必填数组；已知内置引用或明确的本地 `.js` / `.mjs` 绝对路径；空数组不加载插件 |
+| `operations` | 可选完整业务 ID 数组；省略不启动插件业务 runner，`[]` 接管历史但不开放新业务，明确 ID 才启用 |
+| `panel.pages` / `settings` / `renderers` | 可选、互不重复的完整贡献 ID 列表；省略的类别不挂载 |
+
+配置必须是最多 64 KiB 的普通 JSON 文件。不接受相对路径、包名、网络 URL、重复的实际入口或未知字段。外部插件由用户单独安装后，提供明确入口；CLI 不扫描磁盘、不查询市场、不自动执行安装。
+
+加载会校验插件版本、Core 兼容范围、贡献和资源；未知业务/页面或缺失资源导致启动失败，不静默忽略。错误包含 `code`、`stage`、`file`，配置边界错误可附 `field`。兼容范围不是签名或隔离保证，仅加载可信插件。
+
+`panel` 仅用于默认 `web serve`，与 `--panel` 整套 Panel 替换互斥。`api serve` 可使用同一启动机制，但其选择文件必须省略 `panel`。既有 `--provider-extension` 继续加载旧 Provider 工厂，与 `--plugin-config` 互斥；新插件的 Provider 从同一注册器装配，不能把新清单当成旧工厂。
+
+## 登录与重启
+
+普通 `web serve` 不需要 Token 参数。认证目录由 Iris 管理，可显式 `--auth-store /absolute/private-auth`；启动、取地址与重置时保持一致。用 `web login --data-root /absolute/iris/core` 取地址，`web password reset --data-root /absolute/iris/core` 重置口令并撤销全部浏览器会话。重置不修改作品或 MCP 授权；手机浏览器无需读取 Termux 私有文件。
+
+固定 `--port` 可保留浏览器站点存储和已导出的 MCP 配置。CLI 保持前台运行，不自动注册后台服务、系统自启或更改客户端配置。认证存储单独取得写者租约，强杀后也需明确核对恢复。
+
+### 旧 Token 模式与 API 服务
+
+`api serve` 仍要求 `--token-dir` 与 `--token-file` 二选一；`web serve` 显式提供这两个参数时选择旧登录模式，与 `--auth-store` 互斥。目录位于 Core 数据根之外，父目录须存在；不存在的末级目录按 POSIX 0700 创建，已有目录须私有且不能是符号链接，不自动调整权限。每次成功启动创建新的 `session-<UUID>.token`，文件为 0600，并在输出中返回实际 `tokenFile`。
+
+旧会话文件保留且内容不覆盖，旧 owner/浏览器登录在服务停止后失效；新启动打开新的 `loginUrl`。已经保存的 MCP 连接使用独立凭据，不依赖 owner Token 的轮换。目录不自动清理旧文件。
+
+链接过期时，使用**本次启动**输出的 `origin` / `tokenFile` 获取新链接，无需重启：
+
+```bash
+dsh-iris web login --origin http://127.0.0.1:3182 \
+  --token-file /absolute/iris/sessions/session-本次UUID.token
+```
+
+原 `--token-file` 行为保持：必须给新的根外文件路径，已有文件会拒绝覆盖。两种登录模式默认端口均为随机端口，需要稳定地址时主动指定固定 `--port`。
+
+## 启用与授权分别进行
+
+1. `entries` 装载可信实现，贡献进入实际目录。
+2. `operations` 开放服务业务，`panel` 选择界面入口；不授予任何连接权限。
+3. 在工作台“客户端”创建连接，选择准确插件业务与 `read/execute/stop` 中需要的操作权限，再导出 stdio 或 HTTP 配置；配置导入目标 harness 后才会连接。
+
+媒体生图、改图、语音等仍使用原 `--allow-execution --provider-config ...` 及功能选择；上传/创建、持久选择、供应商管理各有独立开关。启用插件业务不连带开启这些媒体写权限。
+
+启动失败或退出时，CLI 先关闭服务、任务 runner 和租约，再释放插件；插件清理异常会报告，但仍尝试其余清理。启动后的配置与模块不会热加载，需要明确停止、核对后重启。业务仍按原 UUID 和准确版本恢复记录，不自动重做；插件缺失或停用时可用 `entries:[]` / `operations:[]` 启动历史读取，原作品继续保留。
+
+程序化装配仍可使用公开 [插件 SDK](PLUGINS.md)，适合已有 Node 宿主；CLI 启动不需要手写启动脚本。

package/docs/PROVIDER_ADAPTER_CONTRACT.md

@@ -6,6 +6,8 @@ Iris 0.2.3 提供 `music` Task能力与 Chat Completions 内嵌音频 Adapter（
 
 ## 目标与依赖方向
 
+beta.1已提供统一插件的[Provider 工厂上下文 v1 与公开类型](PROVIDER_PLUGIN_CONTRACT.md)，并随包分发[独立万相 Provider 模板](../templates/provider-starter/README.md)。本页保留内部生命周期说明；Adapter v0、工厂上下文 v1 和 Task 持久版本相互独立，完整 SDK 尚未冻结。
+
 ```text
 Action / Task watcher / recovery / model discovery
                        │ canonical operation/result
@@ -25,7 +27,7 @@ Action / Task watcher / recovery / model discovery
 
 ## 描述结构
 
-协议工厂由内部注册表选择；0.2.0 基线提供 `dashscope` 和 `openai-images`，0.2.1 另有 `openai-chat-images` 与 `openai-responses-images`，不提供公开注册 API。生图模型可通过可选 `imageProtocol` 覆盖账号默认；选择、实测与 Task binding 共用有效协议，详见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议)。未知的显式 `mediaProtocol` 保留原值，调用时以 `IRIS_PROVIDER_PROTOCOL_UNSUPPORTED` 在联网前拒绝；错误只包含合法协议标识，不回显端点或凭据。
+已发布版本的协议工厂由内部注册表选择；0.2.0 基线提供 `dashscope` 和 `openai-images`，0.2.1 另有 `openai-chat-images` 与 `openai-responses-images`。面向 0.3 的0.3 beta另提供[实例级 Provider 扩展首版](PROVIDER_EXTENSIONS.md)，经实验性窄入口显式加载可信协议；这不代表完整 SDK 冻结。生图模型可通过可选 `imageProtocol` 覆盖账号默认；选择、实测与 Task binding 共用有效协议，详见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议)。未知的显式 `mediaProtocol` 保留原值，未注册时在联网前拒绝；错误只包含合法协议标识，不回显端点或凭据。
 
 未配置协议或选择 `auto` 时，官方端点可识别为对应协议；其他端点继续使用 OpenAI Images 兼容路径，并标记 `protocolInferred:true`。该标记表示尚待用户确认兼容性，不代表已经验证成功。显式选择协议会清除标记；旧记录中已保存的明确协议不追溯猜测其来源。CLI 与 DSH 共用选择逻辑，Task binding 绑定最终实际协议与端点。
 
@@ -65,6 +67,8 @@ Core Attempt 持久化 `providerId::modelId` 复合身份，具体 Provider Adap
 
 `accepted` 不是独立网络操作，而是异步 `submit` 的受理结果。它必须携带非空远端任务 ID；同步成功使用 `completed`，并提供 canonical `artifacts`。迁移期仍保留可直接读取但不随 JSON 序列化的旧 `value`，供 0.1.4 调用方使用。四态提交和自动 failover 规则继续以 [Provider 提交契约 v0](PROVIDER_SUBMISSION_CONTRACT.md) 为准。
 
+当前源码的内置图片、视频、语音、音乐、转写提交及直接视觉传输禁止自动跟随HTTP重定向；输入上传也不自动重发正文到第二个地址。已派发的计费提交遇到重定向时保留受理未知，不用末跳401/403推断首跳未受理，也不借此切换模型。可信Provider扩展应遵守同一费用边界；媒体下载保留其已有重定向语义。从源码运行`tests/provider-submit-redirects.mjs`可核对同源/跨源307、308、原Task/Attempt及下载对照；它不调用真实计费服务。
+
 ## poll、cancel 与交付事实
 
 `poll` 的终态不能互相折叠：
@@ -84,7 +88,9 @@ Core Attempt 持久化 `providerId::modelId` 复合身份，具体 Provider Adap
 
 Host 和 CLI 通过 `prepareProviderInput(adapter, { model, filePath, signal?, timeoutMs? })` 调用可选准备能力，不能自行绕过 Adapter 上传。DashScope 的 Adapter 闭包持有实际凭据与媒体端点并实现临时上传；OpenAI Images 明确不支持。未实现时在网络调用前抛 `IRIS_PROVIDER_INPUT_PREPARATION_UNSUPPORTED`。返回的 `{url}` 只供紧随其后的提交读取，属性不参与 JSON 序列化，不能进入 Task、日志或能力快照。
 
-上传错误经 Adapter 映射与脱敏，固定为 `stage=upload / acceptance=not_accepted`；这组字段属于返回调用方的安全错误分类，**不等于已持久化的 Core Attempt stage**。上传属于 Host/CLI 输入准备，只有随后真正调用 `submit` 才跨越可能计费的受理边界。S2V 已迁入 Core：先持久化 Attempt，再按实际候选账号上传首帧和音频，上传失败可写入该 Attempt，且不调用生成 submit；Core 转写的 `audio_path` 在创建 Task 前上传，失败会直接返回且不创建 Core Task，也不会调用 submit。这是 D-12 当前采用的路径 B；若未来要求把准备失败纳入 Core 事实，须另行评审路径 A，不能由错误字段反推已经落盘。
+上传错误经 Adapter 映射与脱敏，固定为 `stage=upload / acceptance=not_accepted`；这组字段属于返回调用方的安全错误分类，**不等于已持久化的 Core Attempt stage**。只有随后真正调用生成 `submit` 才跨越生成请求的受理边界。S2V 和固定转写 Flow 先持久化 Attempt，再按实际候选账号准备输入；上传失败可写入该 Attempt，且不调用生成 submit。
+
+beta.1也将独立 CLI `run transcribe` 的 `audio_path` 统一放入原 Attempt：先获得写者，再建 Task/Attempt，按每个候选自己的账号上传；仅明确未受理才继续后备候选，取消会中止上传并停止候选链。静态确认全部协议均未实现上传时，在网络和 Task 创建前返回稳定错误（数据根可能已初始化）；实际上传失败保留 Attempt，签名 URL 和本地路径不入任务记录。旧发布版本的该 CLI 分支仍是先上传后建 Task 的 D-12 路径 B；通用 `prepareProviderInput` 本身不承诺持久化，不能只按错误字段反推已经落盘。
 
 ## 错误与取消传播
 

package/docs/PROVIDER_CREDENTIALS.md

@@ -0,0 +1,67 @@
+# 供应商环境凭据引用（当前源码）
+
+此功能从 **0.3.0-beta.1** 提供，旧alpha.1和稳定0.2.7不会解析此引用；不要用旧版本编辑新增引用的配置。原有内联 `apiKey` 配置继续可用，不自动迁移。
+
+## 配置来源
+
+在 Core「模型服务」的供应商编辑页，凭据操作选择「引用环境变量」，填写名称，例如 `IRIS_MEDIA_KEY`。保存只写名称，可以在变量尚未就绪时先保存。页面区分未就绪、已就绪和值无效；保留时名称只读，修改来源需再次明确选择。取消/放弃草稿不修改原配置。
+
+显式 Provider JSON 的对应字段为：
+
+```json
+{
+  "providers": [{
+    "id": "media",
+    "name": "My media service",
+    "baseUrl": "https://example.com/v1",
+    "mediaProtocol": "openai-chat-images",
+    "apiKeyEnv": "IRIS_MEDIA_KEY",
+    "models": [{ "id": "your-image-model", "capabilities": ["image-gen"] }]
+  }],
+  "assignments": { "image-gen": ["media::your-image-model"] }
+}
+```
+
+地址和模型仍需换成实际服务支持的值。变量名须符合 `[A-Za-z_][A-Za-z0-9_]{0,127}`；值须非空、最多8192字符且为可打印 ASCII 文本，使用时去掉首尾空格。变量未设置、空白或值无效均不发送请求。
+
+同一供应商的 `apiKey`、`apiKeyEnv` 和 `dshProvider` 不得混存。Web「保留」保留现有来源，「填写/替换」换为内联 Key，「引用环境变量」换为引用，「清除」移除两种手动来源。CLI `providers set` 明确提供内联 Key 或环境引用时，会替换另一种手动来源。已有配置备份仍可能包含以前保存的内联密钥，不会因切换来源而自动清理。
+
+beta.1修复将持久来源互斥统一用于配置读取、CLI 和 Web 保存：`dshProvider` 条目不能附加普通 `baseUrl`、`apiKey` 或 `apiKeyEnv`，空串或null也不作为隐式换源；`mediaBaseUrl`只能省略或留空，非空同样拒绝。DSH引用的实际端点与密钥均由宿主解析，工作台不提供媒体地址覆盖。若要改成手动连接，应新建供应商。非法混存拒绝保存，读取时报错并保留原文件，不因新的来源约束隔离或自动迁移配置。地址和密钥字段的null/非字符串编辑在写入前拒绝，保留原磁盘和内存状态。DSH合法的端点/密钥内存副本仍可使用，不属于持久配置。
+
+DSH 的[宿主连接引用](DSH_PROVIDER_CONNECTIONS.md)继续走自己的宿主凭据端口，不会把 DSH 配置中的引用自动解释为 Core 环境变量。首片在 Core Web/CLI 提供配置入口，DSH 原工作台没有新增此编辑控件。
+
+## 启动与轮换
+
+变量必须提供给**启动 Core 的进程**。例如在 Bash/Termux 中，隐藏输入后导出，再执行原启动命令：
+
+```bash
+read -r -s -p 'Iris API key (typing hidden): ' IRIS_MEDIA_KEY
+printf '\n'
+export IRIS_MEDIA_KEY
+node bin/dsh-iris.js web serve --data-root /absolute/core \
+  --provider-config /absolute/providers.json --allow-provider-management
+```
+
+上面适用于已有专用根/配置；创建步骤见 [Core 快速开始](CORE_QUICKSTART.md)。也可由自己的服务启动器注入环境。Iris 不扫描或加载 `.env`，不执行凭据命令，也不修改 shell 启动文件。密钥输入不可见，不需要贴进聊天、页面或启动参数。
+
+另一个终端中的 `export` 不会更新已经运行的 Core。轮换后，应让新启动的服务继承新值；正常停止后按原数据根、连接目录和端口重新启动。页面刷新只重新读取当前进程的状态，不会读取另一个 shell 的环境，也不会自动重启服务。
+
+## 调用与恢复
+
+- 未就绪的连接不进入新请求候选；显式选择它会报 `IRIS_PROVIDER_CREDENTIAL_UNAVAILABLE`。自动模型池继续按其他合格项和原有功能策略工作。
+- 检查连接、目录及业务调用在缺少所需凭据时拒绝网络调用。模型目录仍可返回空候选，供应商配置仍可查看/编辑；`config check` 的格式有效不等于环境已就绪或上游认证成功。
+- 每个 Adapter 捕获本次解析出的值，后续新操作使用当时的进程环境。已有 Task 仍核对准确供应商、端点、协议和插件依赖；Key/变量名不加入 Task 身份。
+- 原 Task 缺少变量时不能借用另一供应商或自动重提。恢复原连接及有效值后，查询/下载原任务；已完整交付的本地结果可继续只读恢复。Key 是否被上游允许访问原任务，由上游账号权限决定。
+- `auth:"none"` 不发送保留的 Key，也不要求引用变量就绪，适用于实际无需认证的端点。
+
+## 权限与数据
+
+只有已开启供应商管理的 owner 能查看/更改变量名。MCP 客户端没有环境或密钥读取工具，也不能访问供应商管理路由。普通模型目录仅展示业务可用性，不交付凭据来源。
+
+Core 仅在调用内存中解析值，写配置与备份时不回填解析结果；切换前的内联配置备份仍按原样保留。Task/Operation 和 API 不保存或返回解析值，错误按本次实际调用的 Key 脱敏。现有可信 Provider 插件仍通过原 `apiKey` 参数获得本次运行副本，公共描述不含值。插件是可信代码，这不是 Node 代码沙箱。
+
+摘要中的精确脱敏先于截断和格式化。上游模型ID中包含本次完整Key时，包括带前后缀和短测试Key重合，目录读取按协议错误拒绝整份响应，保留原配置和上一份完整缓存，不导入虚构替代ID。Core HTTP返回502和`IRIS_PROVIDER_DIRECTORY_CREDENTIALS`，CLI提供同一错误码；正常目录读取保持真实模型ID。无需认证的服务使用`auth:"none"`，不要借会与模型ID重合的短字符串充当测试密钥。
+
+beta.1修复也覆盖ComfyUI静态工作流检查：Core CLI/HTTP及DSH工作台的已保存模板、草稿报告，嵌套数组/对象中的字符串值与属性名都先逐层精确脱敏，再编码为JSON。脱敏使用本次检查开始时捕获的凭据，环境随后轮换不改变本次匹配；`auth:"none"`未发送但保留的Key也参与匹配。检查仍只读取节点定义，不写配置或生成作品。
+
+owner 保存契约沿用 v0，新增 `{ "action":"env", "name":"IRIS_MEDIA_KEY" }`。`keep/clear` 不接受额外字段，`replace` 只接收 `value`，`env` 只接收 `name`；修改继续受原 revision、锁、私有备份与原子写入保护。环境值变化本身不改变配置编辑 revision；状态与目录/可用性绑定会重新读取当前值。

package/docs/PROVIDER_EXTENSIONS.md

@@ -0,0 +1,82 @@
+# Provider 扩展首版（0.3 beta）
+
+0.3.0-alpha.1 已提供实例级媒体协议注册及显式加载可信扩展，稳定版 0.2.7 尚不包含此入口。`@mokuyoaxis/dsh-iris/provider-extensions` 是实验性 v0 窄入口，不是完整 Core SDK，也未承诺长期兼容。下列命令适用于beta.1；旧alpha.1只支持原有窄入口，新增工厂上下文、网络与环境引用需beta.1。
+
+六类内置协议（含 [ComfyUI API 工作流](IMAGE_GENERATION.md)）和外部协议消费同样的描述及 Adapter 契约；独立 CLI/API 使用自己的注册实例。当前 DSH 嵌入入口没有新增外部模块加载设置，原有工具、Skills 和存储规则保持。
+
+alpha.1 另提供 [Core 插件贡献 v0](PLUGINS.md)：Provider、业务操作、Web 页面/设置及作品渲染器共用身份、兼容、生命周期和依赖描述。新入口为程序化 `plugins` SDK 和[显式启动配置](PLUGIN_STARTUP.md)；本页的工厂及 CLI 参数继续保留。插件 Provider 的 Task/Attempt 记录准确依赖并纳入 binding，旧扩展的无插件绑定保持；Web 按明确选择挂载，MCP 从实际目录和用户授权装配，不因加载插件自动扩权。
+
+## 显式使用
+
+扩展通过已安装包的 JS/MJS 入口绝对路径指定，可重复添加：
+
+```bash
+node bin/dsh-iris.js providers protocols \
+  --provider-extension /absolute/node_modules/my-iris-extension/index.mjs
+
+node bin/dsh-iris.js run image \
+  --data-root /absolute/new-core --provider-config /absolute/private/providers.json \
+  --provider-extension /absolute/node_modules/my-iris-extension/index.mjs \
+  --input '{"prompt":"a landscape","model_ref":"my-provider::my-model"}'
+
+node bin/dsh-iris.js web serve \
+  --data-root /absolute/initialized-v1-core --provider-config /absolute/private/providers.json \
+  --token-file /absolute/private/new-owner.token --allow-execution \
+  --provider-extension /absolute/node_modules/my-iris-extension/index.mjs
+```
+
+`providers protocols` 返回扩展身份/版本、协议、能力和配置字段描述；不包含具体连接值或密钥，不构造 Adapter 或调用模型。**导入的模块及工厂本身仍是可执行代码**，由用户选择可信来源。服务按明确路径加载，不扫描目录、安装包或自动更新扩展。
+
+扩展注册不授予模型用途或 MCP 权限。用户仍需在显式 Provider 文件中填写连接和模型、确认功能分配。既有协议的新供应商通常只需配置，无需额外代码。服务模式下，harness 通过已有授权调用这个 Core，不需获得上游媒体 Key，也不需各自加载同一媒体插件。
+
+beta.1 可在公共配置层使用[环境凭据引用](PROVIDER_CREDENTIALS.md)，已发布 alpha.1 尚不支持。Core 给既有 `createAdapter(provider)` 的运行副本解析普通 `apiKey`，不改变工厂签名或把值写回配置/描述；`apiKeyEnv` 不作为新的协议自定义字段。
+
+beta.1 还增加[实例级出站网络](PROVIDER_NETWORK.md)和显式[出口池/绑定](NETWORK_ROUTING.md)。新统一 Provider 插件使用版本化的[工厂上下文 v1](PROVIDER_PLUGIN_CONTRACT.md)，只借用 Core 的 fetch 端口；本页旧窄扩展的签名和 options 用法保留。内部客户端构造器不通过公开 exports 导出。第三方插件须主动使用提供的端口，Core 不宣称强制拦截可信代码的任意联网。
+
+## 模块契约
+
+默认导出一个工厂，每次创建注册实例会重新调用；工厂可异步返回以下对象。Node 会缓存模块，模块顶层应保持无实例状态，资源由工厂实例持有。
+
+```js
+export default function createExtension() {
+  return {
+    contractVersion: 0,
+    id: 'my-media-extension',
+    version: '1.0.0',
+    protocols: [/* below */],
+    async dispose() { /* release resources owned by this instance */ }
+  };
+}
+```
+
+协议描述字段：
+
+| 字段 | 语义 |
+|---|---|
+| `id`, `label` | 稳定协议标识与显示名称；实例内唯一，重复不覆盖 |
+| `capabilities` | `image-gen`、`video-gen`、`tts`、`music-gen`、`transcribe` 的非空子集 |
+| `normalizeEndpoint(baseUrl)` | 同一端点的稳定表示，参与既有 binding 哈希；公共 `normalizeMediaEndpoint` 提供普通 HTTP(S) 规范化 |
+| `createAdapter(provider, options)` | 同步返回 [Provider Adapter v0](PROVIDER_ADAPTER_CONTRACT.md)，具体网络操作在其生命周期方法中执行；ID 必须匹配连接，协议/能力必须匹配描述 |
+| `supportsImageEdit(modelId)` | 可选；当前模型支持带原图编辑时返回 `true`，默认不支持 |
+| `supportsModel({provider,modelId,capability,checkEndpoint})` | 可选的具体限制；能力集合仍是前提，不扩张用户分配 |
+| `configuration` | 可选字段数组；首版只描述现有 `baseUrl`、`mediaBaseUrl`、`apiKey`，类型分别为 `url`、`url`、`secret`；可含 `required`、`advanced` 布尔值 |
+
+工厂负责声明和按需初始化能力；一次注册不应提交媒体任务。描述只提供已有配置字段的信息，没有新增自定义持久字段、凭据 helper 或 UI 脚本。扩展实现版本与 Iris 包版本、契约版本及 Task 格式版本分别管理；首版验证契约必须为 0，扩展版本使用明确的三段版本字符串。
+
+窄包入口导出 `defineProviderAdapter`、`ProviderContractError`、`normalizeMediaEndpoint`、两个契约版本常量，以及异步 `createProviderRegistry({extensions:[factory]})` / `loadProviderRegistry([absoluteEntry])`。程序化服务可显式传入 `providerRegistry`；提供者拥有其生命周期，服务只释放自己创建的默认注册实例。
+
+## 调用、恢复与释放
+
+扩展 Adapter 经同一候选选择、能力判断、健康/限流、输入校验和 Core Task Runner；图片和音乐的模型级协议覆盖也使用当前注册实例。目录发现与实际模型实测仍需明确操作。常规自动池只按已确认用途选择，不因安装插件新增授权。
+
+注册实例关闭后拒绝新操作，等待当前 Provider 调用结束，再逆序串行执行扩展释放。重复关闭共享同一个释放过程，失败明确报告。应用应先停止请求/runner 和等待 Core 操作，再释放注册实例。首版更新通过受控服务重启生效，不提供在途热替换。
+
+原五类协议的 Task binding 保持原协议和端点的哈希输入；新增 ComfyUI 使用独立的 v2 binding，另纳入模板摘要，不转换旧记录。协议 ID、端点规范化规则及工作流摘要是恢复约定；升级扩展应继续识别原远端任务。缺少扩展、模型协议无效或端点/模板改变时，恢复明确失败，不选择新 Provider 或重新生成；历史 Task/Run/作品仍可只读查看。恢复原配置后，明确观察/继续仍使用原 Task。
+
+Core 会对错误与健康证据中的连接 Key 再做精确脱敏，`auth:none` 不把保留的旧 Key 交给扩展工厂；扩展仍有责任输出正确的受理状态与错误映射。同进程插件拥有 Node 进程的系统权限，窄接口和声明不是系统沙箱。只加载可信代码；不受信任代码隔离不在此版范围内。
+
+## 验证范围
+
+源树的 `tests/provider-extensions.mjs` 覆盖实例隔离、协议描述、旧哈希、冲突/版本、在途释放与失败。`scripts/verify-provider-extensions-package.mjs` 将候选包解到仓库外，复制独立测试插件包，只经上述公开入口接入真实 CLI/API/Core；受控 HTTP Provider 验证原 Task 恢复、原图编辑、Key 接回和图片字节。
+
+验证脚本明确复用已有依赖，不代表重新安装全部依赖或真实供应商付费验收；测试插件和验收脚本不进入 npm 包。0.3 beta另有 [C3 管理 API/页面](PROVIDER_SETTINGS.md)和独立 [Panel/主题](PANEL_EXTENSIONS.md)；当前源码支持上述显式环境引用，其他凭据来源桥、任意 Recipe/工具注册与完整插件市场仍是后续工作。

package/docs/PROVIDER_HEALTH.md

@@ -4,6 +4,8 @@
 
 工作台的“能力状态与检测”与 [功能模型池](FUNCTION_MODEL_POOLS.md) 配套；以下健康证据规则继续适用。
 
+**0.3 beta Core 工作台补充：** 独立[模型服务页](PROVIDER_SETTINGS.md#健康检测与保活)增加六色光谱、模型池排序、连接检查，以及本次 Core 服务内显式开启的轻量保活。连接检查/保活只读取目录或 ComfyUI 服务状态，不写成媒体实测成功；默认关闭，重启不续开。实际验证先打开指定模型草稿，用户点击创作按钮后复用持久任务执行；真实媒体成功受理/同步完成写入对应连接与模型的健康证据。以下“不做定时探测”描述 npm 0.2.7/DSH 的行为，不包含这一默认关闭的连接保活。
+
 ## 工作台检测入口
 
 能力检测默认折叠，只展示六项能力的近期成功与调用受阻摘要；点击“展开检测”后查看图片、视频、语音、音乐、转写、视觉六张能力卡及候选覆盖，例如“2个可用 · 1/2近期成功”。点卡片展开候选模型、最近验证时间和检测操作；供应商中的中文能力标签会直接展开检测区并打开对应详情。桌面随面板宽度排列，手机单列，适配宿主深浅主题。
@@ -43,7 +45,7 @@ Iris 用持久化证据描述“当前配置是否存在、最近是否实际成
 
 ## 什么会改变状态
 
-显式“模型实测”和正常用户任务都会产生证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。成功受理、同步完成或视觉成功会刷新绿色及其成功时间。
+显式“模型实测”和正常媒体任务会产生持久证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。媒体成功受理/同步完成及显式视觉实测会刷新绿色及其成功时间。0.3 beta中，普通看图、定位、OCR 与纯画面摘要成功不再改写供应商配置；明确模型不存在、限流等已知失败仍按原规则记录。主动音轨转写另行创建媒体任务，其证据继续保存。
 
 Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请求或费用。网络错误、5xx、内容安全、用户取消和受理未知不会覆盖近期成功证据。移除 API Key 后回到灰色。
 
@@ -60,6 +62,8 @@ HTTP 状态、供应商错误码和明确错误说明一起决定路由规则，
 
 冷却与停用按 Provider × Model 记录，对同账号该模型的所有能力生效；其他账号的同名模型不受影响。状态持久保存，重启后继续遵守。正常路由、显式生成和 OCR 后续切片都会跳过受阻模型；已受理 Task 仍可观察原远端任务，绝不因此自动重提。
 
+beta.1对新收到的 `Retry-After` 秒数/未来日期及 `retryAfterMs` 提示限制为 **1秒至2,147,483,647毫秒（约24.85天）**，防止超大提示溢出日期或定时器范围。缺失、无效、负值或已过期日期沿用默认60秒；有效的普通冷却值保持原义。由提示计算的持久化截止时间也受JavaScript日期范围约束，超大提示不会把原429错误改成日期异常。已有记录或显式截止时间不自动迁移；额度/预算耗尽继续保持原停用规则，不因冷却上限自动恢复，也不自动重放失败请求。
+
 模型池显示原因及冷却恢复时间，实测按钮保持可用。冷却到期只恢复候选资格，不触发验证请求；颜色按原有证据返回蓝色或绿色。发现、修改分配、改 Key/端点、移除再添加同名模型，以及旧任务成功，都不能解除明确耗尽的停用。显式实测只调用指定模型，失败不恢复，成功解除该账号该模型的冷却或停用。视频/转写实测须用 CLI `models test --input` 明确提供真实素材，未提供时跳过，见 [CLI 管理命令](CLI_MANAGEMENT.md)。
 
 ## failover 与泡泡汇总

package/docs/PROVIDER_NETWORK.md

@@ -0,0 +1,45 @@
+# Provider 出站网络基础（beta.1）
+
+0.3.0-beta.1提供实例级请求端口，可通过独立CLI管理[出口节点与池](NETWORK_RESOURCES.md)，并显式启用[供应商绑定与HTTP/HTTPS代理](NETWORK_ROUTING.md)。**0.3.0-alpha.1 尚不包含这些增量。** N2已完成受控代理和原任务恢复验证，N3另接[网络工作台与Doctor](NETWORK_WORKBENCH.md)。默认继续使用原来的网络环境，不替换已配置的全局 `fetch` / dispatcher，不改代理环境变量或系统路由。
+
+本页描述内部装配边界，不是已冻结的完整 SDK。网络客户端构造器不通过包的公开 `exports` 导出；第三方插件不应依赖私有文件路径。统一插件现在通过[工厂上下文 v1](PROVIDER_PLUGIN_CONTRACT.md)借用只读 `network.fetch`，见[独立万相模板](../templates/provider-starter/README.md)；该上下文与类型从beta.1提供，旧窄 Provider 扩展的 options 用法继续保留。
+
+## 实例与完整操作
+
+一个客户端持有显式的 `fetchPort` 及可选关闭回调；没有显式端口时，在每次请求发生时读取 `globalThis.fetch`，保持原调用行为。显式端口失败直接返回原失败，不自动换用全局请求、不重试、不切换供应商。
+
+Configured Provider 的目录发现、提交、查询、取消（协议已支持时）、下载和输入上传，经同一客户端执行。一次完整操作只登记一次：等待响应正文、分页、上传策略后的对象存储请求、转写结果 URL 和媒体下载完成后才结束，收到响应头不算操作完成。错误映射仍为同步函数。
+
+上传返回后无需使用的正文、转写结果下载的非成功正文会显式取消并等待释放。媒体下载先准备本地目录再请求上游，目录准备失败保留本地存储错误，不留下未读取的网络响应。
+
+调用者拥有客户端的生命周期，关闭顺序为：停止接收业务并取消/等待 Core 在途工作，等待 Provider 注册实例的操作与释放，再释放网络客户端。网络关闭拒绝新操作，等待已登记操作结束后只调用一次关闭回调；已开始操作仍能进行第二跳请求。关闭失败保留并向调用者报告，不重新执行清理。任意插件若忽略取消信号，公共端口不能强制结束它。
+
+路由管理器在后续解析发现配置修订或所引用的代理凭据变化时，也复用这一关闭机制回收旧客户端：已接纳操作保留原快照直到完整正文和多跳结束，新操作使用重新解析的客户端；同一身份不累计缓存历史版本。最终实例关闭包含所有仍在排空的旧客户端。详见[网络路由生命周期](NETWORK_ROUTING.md)；未增加后台强制超时或改变Task身份。
+
+直接使用请求函数的内部代码必须把完整正文处理放在同一次操作内；裸 `fetch` 不是独立的排空跟踪器。测试可注入受控请求实现；显式路由由实例持有的Undici客户端执行。Task操作还提供Core路线持久化端口，不依赖CLI或Web的可选观察回调。
+
+## 当前接入矩阵
+
+| 路径 | 当前源码支持 | 实际边界 |
+| --- | --- | --- |
+| DashScope Configured Provider | 目录分页、图片/视频/TTS/转写的已有提交与查询、上传策略及对象存储、结果 URL 与媒体下载共用客户端 | 保留原受理状态和超时；没有新增模型、协议或重试 |
+| OpenAI Images / Chat Images / Responses Images | 现有目录、同步生成和已有产物下载使用注入端口 | 不因此新增异步查询、远端取消或原图编辑 |
+| Gemini Web Music 网关 | 目录与既有同步生成使用注入端口，内联作品照常入库 | 是网关扩展协议，非官方 Gemini 音乐 API；没有新增持久 Music 流程 |
+| ComfyUI Configured Provider | 沿用已有 `fetchPort`，目录检查、prompt/history/queue/view 使用同一客户端 | 保持已有 API 工作流及取消边界，无真实 GPU 新验收 |
+| 模型目录刷新服务 | 显式传入客户端后，共用该客户端发现；进行中的请求按客户端及注册实例隔离 | 相同客户端仍去重；已有完整目录快照及持久绑定规则不变 |
+| CLI / 服务共享候选与原 Task 装配 | 按Provider、模型、Task及明确的网络要求解析客户端，图片/视频/音频候选及原Task都走该端口 | 解析参数不含Key；包装目录必须匹配显式network-config，旧配置继续继承原环境 |
+| Core供应商连接检查、模型实测、ComfyUI设置检查 | 显式解析该供应商客户端并保持目录包装 | 缺少匹配网络上下文会拒绝，不静默调用默认fetch |
+| 旧DSH原生调用、DSH借用模型/浏览器 | 保留已有装配和宿主接口 | 尚未增加DSH网络资源管理；借用服务的实际出站归宿主管理 |
+| 独立视觉模型端口 | 旧配置继续原有接口及fetch注入 | 包装目录明确拒绝尚未接入的视觉路径，避免绕过网络要求直连 |
+| 统一插件 Provider | Core 传入工厂上下文 v1，只借出 fetch，并自动管理完整生命周期方法；缺失匹配的显式网络上下文时拒绝 | 插件须等待正文/多跳请求；不能自行 run/dispose；同进程代码仍可自行联网，这不是网络沙箱 |
+| 旧窄 Provider 扩展 | 保留 options 与内部 Configured 装配的 transport / fetchPort 注入 | 不把新上下文签名强加给旧工厂；需要主动遵循旧端口约定 |
+
+下载重定向沿用请求实现的策略，TLS继续校验。受控真实代理验证了HTTP→HTTPS产物重定向、代理/供应商认证隔离、两个供应商并发、环境及宿主dispatcher并存；这些测试不证明用户真实Clash或系统TUN的具体行为。
+
+## 验证与后续
+
+Core服务可显式装配[有界媒体调度](MEDIA_SCHEDULING.md)，按实例、供应商和模型共同限制请求。它在已有Undici dispatcher前排队，重定向每跳重新入门，正文结束才释放HTTP名额；继承出口继续借用原dispatcher，显式出口继续使用原实例代理。远端已受理数量由Core Task事实另行控制，不使用HTTP连接数代替；未知受理不因此重放。
+
+以下测试和`scripts/`开发验收命令从源码仓库根运行，不随npm包分发。`tests/provider-network.mjs` 验证实例隔离、并发与单项取消、完整正文/多跳排空、关闭失败、无隐式回退和共享候选装配。`tests/provider-network-integration.mjs` 使用本地 HTTP 服务验证目录、实际 multipart 上传、提交/查询、转写结果和下载，并验证忽略的响应流在关闭前释放；不会访问真实供应商或生成计费媒体。原协议、目录、凭据与 Core 流程另作定向回归。
+
+独立节点/池、私有环境认证引用、owner CLI与[N2绑定/持久任务要求](NETWORK_ROUTING.md)已进入beta.1。`scripts/verify-network-proxy.mjs` 和 `scripts/verify-network-task-proxy.mjs` 分别覆盖真实代理传输及Core/CLI/API、原任务跨进程恢复。[N3](NETWORK_WORKBENCH.md)复用实际Core客户端做有界GET与有限IP观察，静态读取不联网；不携带Provider Key，不代表模型实测。创建但未绑定不改变网络；显式失效不悄悄直连。系统TUN、用户Clash和第三方插件的任意流量不在当前可证明的控制范围内。

package/docs/PROVIDER_PLUGIN_CONTRACT.md

@@ -0,0 +1,24 @@
+# 统一 Provider 插件最小契约（beta.1）
+
+本页列出0.3.0-beta.1冻结的最小Provider边界；完整SDK另行演进。新模板见 [`templates/provider-starter`](../templates/provider-starter/README.md)。它独立实现万相 wan2.6 公开异步接口，不依赖 Core 私有 transport。**需要 `0.3.0-beta.1` 及工厂上下文v1能力标记；旧alpha.1不支持。**
+
+| 边界 | 本片确定的约定 |
+| --- | --- |
+| 身份与版本 | Plugin v0 清单，插件及 Provider 贡献各有独立版本和完整 ID；兼容区间检查 Core 版本，模板另检查工厂能力标记 |
+| 工厂 | 同步 `createAdapter(provider, context)`；旧只收一个参数的统一工厂可忽略新增参数；旧窄 Provider 扩展的第二参数保持原用法 |
+| 连接副本 | 浅冻结的运行副本；Core 将显式 `apiKeyEnv` 解析成当次 `apiKey` 并移除引用字段，`auth:none` 不提供 Key；缺失引用在工厂/HTTP 前拒绝，不写回配置 |
+| 上下文 v1 | 导出 `PROVIDER_FACTORY_CONTEXT_VERSION = 1`；只提供只读 `{contractVersion:1, network:{fetch}, modelId?}`。没有 registry、通用环境读取、存储、代理配置、dispatcher、run 或 dispose |
+| 生命周期 | 六个操作各声明 supported 或有原因的 unsupported；submit/mapError 必须实现。mapError 同步；其余完整方法由 Core 登记和等待 |
+| 网络所有权 | 工厂内不能请求；仅在已接纳的生命周期方法内借用 fetch，方法返回后拒绝迟到请求。插件等待正文、上传与后续页；Core 停止接纳、排空操作再释放资源，释放错误可定位且不重复执行清理 |
+| 出口与调度 | 使用相同 Core 端口参与绑定、任务网络要求、HTTP/RPS 和冷却；显式网络要求缺失时拒绝，不借默认出口。默认继承现有网络环境，不改全局 fetch、dispatcher、环境或系统路由 |
+| 提交与恢复 | accepted 必须有原 remoteTaskId；not_accepted、accepted、unknown 分开。Core 保存 Task/Attempt 的准确插件/贡献依赖；缺失或错版阻止继续，恢复准确版本才观察原任务，不重新 POST |
+| 执行与存储 | Core 拥有 Flow/Task/Operation、幂等、单写者、权限、作品及交付记录；插件只写 Core 提供的待交付新文件，不自建队列或直接改 Core 元数据 |
+| 注册与授权 | Provider 使用已存在的媒体流程与 MCP 工具；目录、安装或启用不自动授予连接权限，用户按功能选择和缩权 |
+
+`network.fetch`接受Node原生`Request`、URL/字符串及`RequestInit`，包括原生`FormData`上传；显式代理的类型转换由Core传输边界处理。插件不需要导入Undici或替换全局构造器。上传文件后应等待响应正文完成，再结束生命周期方法。
+
+公开类型由 `@mokuyoaxis/dsh-iris/plugins` 导出，包括 `ProviderFactoryContext`、`ProviderConnection`、生命周期请求/结果和 `ProviderContractError`。该异常与旧 `provider-extensions` 导出是同一个类。429 可附临时 `retryAfterMs` 提示供 Core 冷却；它不是新增 Task 持久字段。安全错误不能包含原始凭据、上游正文或签名下载地址。
+
+模板保留具体协议的边界：目录从实际上游响应读取，确认前不填模型池；仅支持明确实现的 Wan 模型；对模糊提交不重试、不换模型/出口；本地停止不冒称远端取消。其配置通过公开 CLI 初始化新根，无自动数据迁移、自动安装、热加载或扫描宿主磁盘。
+
+借出的端口是合作约定，可信插件仍能自行导入 Node 模块联网或读文件；这不是进程沙箱。历史窄扩展、DSH 借用服务和独立视觉路径的范围继续见[出站网络接入矩阵](PROVIDER_NETWORK.md)。没有将全部 Core 内部函数、任意插件设置存储或所有平台宣布为稳定 SDK。

package/docs/PROVIDER_SETTINGS.md

@@ -0,0 +1,91 @@
+# Core 供应商、模型池与健康检测（0.3 beta）
+
+此页描述0.3.0-beta.1的配置界面，**稳定 npm 0.2.7 不包含该入口**。它管理 Iris 媒体供应商；harness 接入权限仍在连接中心管理，各家聊天模型登录与 OAuth 不由此页接管。
+
+beta.1 另有可选的[环境凭据引用](PROVIDER_CREDENTIALS.md)：保存变量名、在 Core 进程中解析值，原有内联 Key 和 DSH 连接引用保持。
+
+beta.1另有[网络出口页](NETWORK_WORKBENCH.md)。独立开启网络管理后，供应商卡片与功能池显示配置出口，已保存连接可跳转设置；模型池继续决定调用哪个候选，出口绑定独立保存。空/停用池明确阻止新请求，旧供应商目录需要另存启用，不自动迁移。网络GET检测不代替下面的目录、认证或媒体验证。
+
+## 开启管理
+
+使用已有私有配置和专用 Flow 根。需要新配置时，先明确初始化，不覆盖已有文件：
+
+```bash
+node bin/dsh-iris.js config init --provider-config /absolute/new-providers.json
+node bin/dsh-iris.js web serve --data-root /absolute/existing-flow-root \
+  --provider-config /absolute/new-providers.json --allow-provider-management
+```
+
+普通工作台使用访问口令：首次打开启动输出的 `loginUrl` 设置，之后用普通地址。完整空配置、执行根初始化和登录恢复见 [Core 快速开始](CORE_QUICKSTART.md)；显式 Token 模式保留兼容，不是必填参数。
+
+管理是独立开关，只有 owner 可用；普通连接、MCP read/execute、连接管理、媒体执行或选择均不隐含此权限。可以只管理配置，不启用媒体写入；会话 `readOnly` 只描述媒体权限，`providerManagement` 单独描述管理权限。
+
+保存供应商也意味着信任其网络端点和返回的媒体地址；现有下载可跟随上游重定向，没有按目标网段隔离。HTTP 保留用于本地网关与 ComfyUI，远程明文地址会暴露传输中的凭据或内容，应使用 HTTPS 或受控隧道。响应大小/超时限制不代替网络目标限制；普通 MCP 连接不能借供应商管理修改地址。
+
+同时改图时，在已明确初始化的 v1/v2/v3 执行根另加 `--allow-execution --allow-selection`；文生图需 v2/v3 根，见 [文生图与 ComfyUI](IMAGE_GENERATION.md)。[语音合成与转写](AUDIO_FLOWS.md)需显式新 v3 根和执行开关，音频结果无需图片选择。沿用原配置 JSON 与 CLI；不迁移旧根，服务启动不自动创建配置。
+
+## 配置流程
+
+“模型服务”分为供应商、功能模型池、健康检测三个入口。供应商先显示名称、地址、模型数和配置状态的概览卡片，按六色鸢尾使用极浅点缀；“已配置”不代表实测通过。点击服务卡片或“添加服务”进入编辑，连接、模型与用途、ComfyUI工作流分组显示。顶部返回与底部取消使用同一草稿确认，未保存修改可保留或明确放弃；保存结果未确认时，先重新读取核对。隐藏分组中的必填连接字段无效时，会显示该分组并定位字段。
+
+1. 从“模型服务”或创作区“管理模型”进入，选择卡片或“添加服务”。选预设/自定义，填写名称、Base URL 和认证；高级连接设置默认折叠。稳定 ID 自动生成，不作为日常重命名入口。
+2. 现有 Key 只显示存在状态，不回显。明确选择保留、填写/替换或清除；当前源码也可选择环境变量引用并查看就绪状态。服务实际不要求认证时可选“无需认证”，保留的旧 Key 不发送。
+3. 可以先仅保存连接，再主动读取目录；目录只使用已保存连接。也可直接手填模型 ID。
+4. 勾选图片/视频/语音/音乐/转写/视觉用途再保存。新勾选用途时，原本停用的对应功能会改为自动选择，摘要明确列出。已有自动/手动设置不因打开页面而改变。
+5. 返回列表，进入“功能模型池”独立选择自动、手动排序或停用。手动勾选模型后可上移/下移，按显示顺序保存；取消可放弃未保存的池设置。自动和手动均沿用运行时的协议、连接、限流与模型可用性过滤，按顺序优先选择，不是跨请求轮询。手动空池不回落到自动。
+
+目录结果暂存在页面，搜索/加入草稿不写配置、不批准用途。目录元数据与实际协议支持不同；标注用途后运行时仍验证协议、限流和可用性。模型级图片/音乐协议在折叠项中选择：图片可沿用供应商默认，音乐必须明确选择，空值不回落到供应商默认。`gemini-web-music` 的显示名称统一为“Chat Completions（内嵌音频）”，不限定供应商或模型名称，详见[音乐接口](MUSIC.md)。
+
+beta.1 的 Core Web/MCP 支持图片生成/编辑、v3/v4 根的语音合成/转写，以及新v4根的[文生视频](VIDEO_FLOWS.md)；音乐/视觉可配置用途，创作继续使用已有DSH/CLI入口。配置用途、接口支持和创作入口覆盖是不同事实。
+
+ComfyUI 预设提供已有服务地址和默认折叠的 API 图/Iris v0/v1 模板导入。每份工作流作为一个明确的图片模型，绑定正向提示词、输出和可选尺寸节点；可勾选已有标量、命名参数并预览表单。导入不执行，同名替换明确确认，加入草稿并保存后才能从创作页选择。目录检查只验证服务并列出已配置工作流，不把远端 checkpoint 自动当成可调用工作流。流程与限制见 [ComfyUI 入口](IMAGE_GENERATION.md#comfyui-入口)。
+
+快速填写或直接切换媒体协议进入 ComfyUI 时，供应商编辑区显示 `ComfyUI Studio` 标识并播放一次鸢尾渐变扫光；编辑普通字段不会重复播放，离开模式会清除标识。减少动画设置下保留静态模式提示，不播放扫光。切换本身不保存配置或调用服务。
+
+ComfyUI 切回“自定义兼容服务”会恢复本次编辑中先前的 API 地址、媒体地址、协议、认证和未提交密钥；没有此前 API 草稿时，显示空地址的通用 API 草稿，不沿用 ComfyUI 地址。切换前的连接字段仅暂存在当前页面内存，重新载入或退出后清除。显式选择 OpenAI/百炼预设会使用相应地址、协议与 API Key 认证，并清除旧媒体地址覆盖；供应商名称与模型列表仍由用户确认。已保存 ComfyUI 配置重新打开时，快速选项与实际协议一致。
+
+Core 参数表单与 `POST /api/v0/provider-management/workflow-check` 已接通：owner 提交 `{expectedRevision,modelRef,workflowParameters?}`，或使用 `{expectedRevision,providerId,comfyWorkflow,workflowParameters?}` 检查未保存模板。草稿只能使用已保存、启用的 ComfyUI 连接，不接受临时地址或凭据；只查询节点定义，返回静态问题和可用选项，不写配置、不创建 Task、不入队。需同一供应商管理开关，仍受 Host/Origin、revision 与请求大小限制；静态通过不代表推理通过。DSH 的独立入口见 [DSH 工作台](IMAGE_GENERATION.md#dsh-工作台入口03-alpha)。详见 [参数模板与检查](IMAGE_GENERATION.md#comfyui-参数模板与只读检查后端)。
+
+连接/模型保存与独立模型池保存均复用原锁、revision 摘要、0600 备份与原子写入。未改动供应商、模型与额外字段保留。原模型可清空用途，新模型可撤销添加。内联配置及其备份仍含 Key；环境引用只保存名称，但切换前的旧备份可能仍含内联 Key，应保存在当前用户控制的私有位置。
+
+环境引用的 owner 投影另返回 `apiKeyEnv` 名称和 `credentialStatus:"ready"|"missing"|"invalid"`；`hasCredential` 表示当前值是否就绪，不回显值，`auth:none` 的可用性独立判断。
+
+设置 `revision` 是不透明的编辑版本：账号、凭据、模型、分配或其他配置变化仍冲突，单纯的健康时间与目录缓存更新不作编辑冲突。保存基于最新配置合并，并在锁内复核原文件字节，保留已有的健康证据；不能用该 revision 替代文件摘要或跳过写入锁。
+
+编辑页“停用与删除”默认折叠。停用保留连接、模型与池设置，可原地恢复；删除先显示模型和当前工作区的任务/流程影响，再独立确认。当前根中未开始的流程、运行中任务、受理或结果未知、待交付或交付失败、取消待确认会阻止删除。成功交付及已失败/取消的历史保留，不删除作品或任务；同时移除该供应商的手工池引用，不把空手工池改成自动。只检查当前 Core 根，其他工作区和独立 DSH 消费者不扫描；本地删除也不吊销上游 Key，私有配置备份保留原凭据。
+
+修改地址、认证或协议使相应旧验证失效，限流/额度保留原语义。旧 Task 仍绑定原端点和协议；变更地址、停用或清除认证可能阻止恢复，不改绑或自动新提交。
+
+## 健康检测与保活
+
+六色“能力光谱”分别显示六类能力的当前候选、近期成功和参与项；候选详情默认折叠，列出顺序、未进入池/协议不支持/模型不存在/冷却/额度受阻等原因与最近证据时间。读取和刷新仅汇总本地配置与持久证据，不请求供应商。
+
+“检查连接”只读取已保存连接的模型目录；ComfyUI 使用原服务状态检查。结果单独记录时间，连接可达、目录列出、Key 存在或声明用途均不算媒体成功。可以显式开启每1/5/15分钟的轻量保活，默认关闭、首次等待所选间隔、不重叠请求。仅支持已有轻量读取的内置协议，外部扩展保留手动目录入口。设置与检查结果只在本次 Core 服务中保留；停用、删除、关键连接变化或服务关闭会停止，服务重启默认关闭。它不是持久监控或媒体可用性保证。
+
+执行开启且存在相应入口时，候选模型可“准备功能验证”：图片打开指定模型的小样本草稿（旧图片根为改图），语音预填“你好”，转写仍需用户音频；ComfyUI 沿用实际工作流参数。打开草稿不提交，只有点击创作页原生成/转写按钮才进入 Core Run/Task/Operation，可能计费，不批量测试。视频、音乐、视觉仍明确显示已有 CLI/DSH 范围。也可用原 `models test` CLI 显式测试。
+
+真实媒体的成功受理/同步完成沿用精确连接、模型、能力绑定，写入近期健康证据；这不额外证明最终下载或可播放。改变关键连接后旧证据失效，冷却和明确额度停用保持原规则；普通任务成功不能代替显式实测解除额度停用，见[健康状态](PROVIDER_HEALTH.md)。
+
+保存中禁用重复提交。revision 冲突保留草稿，拒绝覆盖；回包丢失标记未知，不自动重试。选择“重新读取”并明确确认放弃草稿后，读取文件的实际结果。刷新、目录和保存不生成媒体。
+
+## 管理 HTTP 契约 v0
+
+固定操作启动时的配置路径，浏览器不能传路径、原文件或任意命令。请求沿用 Bearer、Host/Origin、无 CORS、no-store 和净化错误。POST 为 UTF-8 JSON，最多 64 KiB，同实例同时只处理一个管理变更/目录请求。
+
+| 路由 | 语义 |
+|---|---|
+| GET/HEAD `/api/v0/provider-management/settings` | owner 非秘密投影：版本、revision、来源标识、协议描述、供应商、模型、全局功能池；Key 仅存在状态 |
+| GET/HEAD `/api/v0/provider-management/diagnostics` | 当前候选/阻塞原因/有限历史证据及本次服务的连接检查状态；不发起检查 |
+| POST `/api/v0/provider-management/save` | `{expectedRevision, provider, credential, assignments?}`，保存一次，返回新投影，不返回备份路径 |
+| POST `/api/v0/provider-management/policies` | `{expectedRevision, assignments}`，独立保存明确修改的功能模型池 |
+| POST `/api/v0/provider-management/enabled` | `{expectedRevision, providerId, enabled}`，停用或恢复 |
+| POST `/api/v0/provider-management/impact` | `{expectedRevision, providerId}`，只读当前 Core 根的删除依赖及模型影响 |
+| POST `/api/v0/provider-management/remove` | `{expectedRevision, providerId, confirm:true}`，同 Core 写队列重新核对依赖后删除配置，受保护依赖返回409 |
+| POST `/api/v0/provider-management/check` | `{expectedRevision, providerId}`，一次轻量只读检查；失败返回 `ok:false` 与有限分类，不回显上游原文 |
+| POST `/api/v0/provider-management/monitor` | `{expectedRevision, providerId, enabled, intervalSeconds:60\|300\|900}`，本次服务内的显式保活 |
+| POST `/api/v0/provider-management/discover` | `{expectedRevision, providerId}`，返回最多 256 模型、`persisted:false` 与截断标记，不写配置 |
+| POST `/api/v0/provider-management/workflow-check` | 明确模型或已保存连接上的模板草稿，返回静态检查及参数候选；不写配置或入队 |
+
+`provider` 只接受 `id/name/baseUrl/mediaBaseUrl/mediaProtocol/enabled/auth/models`；单次最多 256 模型，每项接受 `id/capabilities/imageProtocol/musicProtocol` 及可选 `comfyWorkflow`。工作流支持 `{version:0,graph,promptNode,outputNode,sizeNode?}`，也支持增加明确 `parameters` 的 v1 模板；Core 导入控件可创建两者，完整 v1 的声明随设置保存。普通保存省略工作流时保留原图，读取只返回摘要和参数描述，不回显 `graph`。未提交的原模型保留。`credential` 为 `{action:"keep"}`、`{action:"clear"}`、`{action:"replace",value:"new-key"}`，当前源码另支持 `{action:"env",name:"IRIS_MEDIA_KEY"}`；各动作只接受对应字段。`assignments` 只含本次修改的能力，值为原有 `{mode:"auto"|"manual"|"disabled",models:[...],hostVision?:boolean}`，不创建第二套格式。
+
+未开启 405、连接越权 403、revision 冲突/锁占用 409、非法设置 400、正文过大 413。已加载的 [Provider 扩展](PROVIDER_EXTENSIONS.md)通过实例描述进入页面；页面不能安装或加载代码。当前源码的环境凭据未就绪会在显式目录/连接检查时返回409及 `IRIS_PROVIDER_CREDENTIAL_UNAVAILABLE`；其他外部凭据来源桥继续后续。

package/docs/PROVIDER_SUBMISSION_CONTRACT.md

@@ -51,6 +51,12 @@ Provider `submit()` 必须返回以下四种结构之一：
 
 错误记录不得包含 `cause`、stack、请求体、响应正文、API Key、Authorization、POSIX/Windows 私有绝对路径或签名 URL。调用方可以在当前进程中保留原始异常用于调试，但不得把它当作 Task/Attempt JSON 或事件载荷。
 
+## 上游响应与交付限额（0.3 beta）
+
+内置 HTTP 媒体传输按实际响应累计字节，不仅依赖 Content-Length；chunked 或压缩解码后的正文同样计数。元数据/错误 JSON 最多 2 MiB，含内嵌媒体的成功 JSON 最多 128 MiB；产物限额为图片 64 MiB、音频 128 MiB、文本 8 MiB、视频 1 GiB。超限中止读取，下载临时文件在原收尾路径清理，不替换既有目标；超时和取消规则继续适用。这是单个响应/产物限额，不是作品库自动配额或 GC。
+
+超限不会证明生成未受理，仍保留原提交/交付阶段的事实，不触发自动重新生成。交付保留已分类的 network、timeout、provider、protocol、local_io 等错误，不再一律归为本地落盘失败。
+
 ## 当前接入边界
 
 `lib/provider-contract.js`、Task v2 复制落盘原语和零网络 Fake Provider 已冻结本契约。完整图片能力现在都会在请求前写入 Attempt：DashScope 旧异步返回远端 ID 后进入观察；DashScope 新同步、OpenAI Images、聊天生图与 Responses 生图的有效成功响应记为 `completed/accepted`，随后独立推进本地产物交付。异步与同步候选可以在同一个 Task 中安全切换。
@@ -58,3 +64,5 @@ Provider `submit()` 必须返回以下四种结构之一：
 429 等可证明未创建任务的明确 4xx 拒绝可进入下一候选；408、409、425、499、5xx、网络异常、超时和成功响应缺少必要结果一律停止并记录 `acceptance=unknown`。同步生成已经成功后，下载或落盘失败记录为 `outcome=succeeded / deliveryState=failed`，不会重新生成。
 
 视频、转写与 TTS 使用同一受理边界，但提交前输入准备不自动成为 Core 事实。0.2.1 的 S2V 先持久化 Core Attempt，再按实际候选账号上传首帧和音频；上传失败保存安全错误，零生成 submit。Core 转写的 `audio_path` 在 Host/CLI 边界先上传，失败以脱敏的 `stage=upload / acceptance=not_accepted` 返回调用方，零 submit、零 Core Task。准备成功后才创建 Core Task/Attempt 并进入写前 submit；TTS 同步成功则先记 `completed/accepted` 再交付音频。工作台消费稳定的人类状态，并提供重新观察、重新交付、提醒已读/恢复和需确认费用的知情重试。v0.1.4 已将 discovery、submit、poll、cancel、download 与 error mapping 收口到统一 Adapter，并由零网络 conformance runner 覆盖现有 DashScope/OpenAI Images 路径。
+
+上段转写先上传的描述保留旧发布版本的阶段事实。beta.1已将独立 CLI `run transcribe --input '{"audio_path":"..."}'` 的上传纳入原 Task/Attempt，并按实际候选账号分别准备，取消停止候选链；根忙不上传、静态不支持不建 Task，实际上传失败保留原 Attempt。固定转写 Flow 同样在原 Attempt 内准备；通用上传端口本身仍不等于持久化。详见[上传边界](PROVIDER_ADAPTER_CONTRACT.md#可选输入准备与上传边界)。