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

package/docs/PLUGIN_DEVELOPMENT.md

@@ -0,0 +1,39 @@
+# 独立插件开发与验收（0.3 beta）
+
+当前源码提供两类可复制的独立项目。下面的 [`templates/plugin-starter`](../templates/plugin-starter/README.md)包含独立业务身份、Web 页面和 PNG 作品预览器，复用公开对照板实现；另有 [`templates/provider-starter`](../templates/provider-starter/README.md)，独立实现万相 wan2.6 异步协议并贯穿环境凭据、Core 网络/调度与原任务恢复。
+
+**npm `0.3.0-beta.1` 包含这两个模板目录**。业务/页面模板沿用公开SDK；Provider模板使用beta.1的工厂上下文v1，并检查公开能力标记。旧alpha.1不包含模板，也不支持新的Provider工厂上下文。
+
+## 从真实业务开始
+
+复制模板到仓库之外的新目录，按模板 README 安装明确版本的 Core，然后运行 `npm test` 与新目录初始化。两张示例图为纯色 PNG，无个人素材，无供应商账号或模型调用。初始化脚本只创建新私有目录并通过公开 CLI 初始化；若目录已存在则拒绝，失败现场保留，不改已有根或迁移配置。
+
+生成的启动选择文件使用插件入口的绝对路径。可先执行 `plugins inspect --plugin-config ...`，再按打印的参数启动 `web serve`。端口、数据根、连接目录和准确插件版本由使用者明确选择；不扫描用户磁盘或 harness，不自动重启服务。
+
+## 三层选择
+
+| 层次 | 决定什么 | 不代表什么 |
+|---|---|---|
+| `entries` | 导入并激活可信插件，校验身份、版本与兼容范围 | 不自动启用业务，也不创建客户端授权 |
+| `operations` / `panel` | 服务可执行哪些业务，挂载哪些页面/预览器 | 页面挂载不授予任意 MCP 连接权限 |
+| 连接的业务选择与 scopes | 哪个连接可读取、执行、停止哪些准确依赖 | 安装完成不表示客户端已连接或业务实测成功 |
+
+用户在连接页选择 `example.starter-board.create` 并授予 `read`/`execute` 后，才向该连接提供业务调用。调用参数和精确 `dependency` 从实际 `iris_core_plugin_catalog` 获取。图片、视频等媒体组可以全部不选；这里执行的是独立图片业务，而非媒体生成流程。
+
+## 公开边界与生命周期
+
+模板只导入 `@mokuyoaxis/dsh-iris/plugins`、`@mokuyoaxis/dsh-iris/contact-sheet` 和公开 `package.json`（定位 CLI bin）。不引用 `lib/` 实现路径。它没有额外运行时依赖，也没有复制 Core 的执行队列、存储、认证或 MCP 服务。
+
+业务使用公开 Core 命令读取来源、导入结果；来源字段显式声明为 `artifactIds`。Core 校验输入、来源资格和当前授权，持久保存 Operation/输出及准确插件依赖。页面使用共享 API、会话与主题，先保存 UUID 再提交，刷新只查原 UUID；卸载取消请求、清理监听/计时器/图片 URL。预览器读原始 PNG，不生成替代图片。
+
+当前模板复用公开 `contact-sheet` 0.1.0，并明确检查该业务版本。它展示独立插件包的消费和装配，并非另一个原创绘图算法。改变业务语义应审查并提升独立插件/贡献版本；改变依赖实现不能沿用旧版本伪装兼容。Core 实例停止后才能释放共享 registry；新增真实后端资源时在 `activate` 内用 `context.onDispose` 注册清理。
+
+插件是可信代码；有限 Core 命令、借用的 fetch 和 Shadow DOM 都不是任意 Node/浏览器代码的安全沙箱。两类模板都没有增加自动安装、热加载或通用私有设置存储。Provider 最小面、凭据与网络所有权见[审查清单](PROVIDER_PLUGIN_CONTRACT.md)；完整 SDK 冻结与发布仍另定，见 [SDK 契约](PLUGINS.md)与[启动选择](PLUGIN_STARTUP.md)。
+
+## 包外验收
+
+先检查 `npm pack --dry-run --ignore-scripts --json`，再打出真实插件包并在新项目中安装/解包测试。确认 Node 只通过安装的 Core 公开入口解析，页面和 CSS 资源确实进入插件包，且包中没有数据根、令牌、个人背景或仓库私有资料。
+
+模板自检覆盖加载但未启用、连接未选业务、明确授权后的实际 PNG、相同 UUID 的幂等/不同输入冲突、同端口重启后的原连接与结果、版本变化、插件缺失与缩权。证据保留在新建临时目录，服务在 finally 中关闭。真实浏览器和包外制品另行验证，不能用静态 DOM 或协议夹具代替真实业务证据。
+
+重启后保留原 Operation 和已提交的图片；未完成操作显示中断，不自动重做。缺少插件或版本不匹配时，新执行应拒绝，原历史与合格图片仍可按授权读取。业务执行的持久性不由前端或 MCP 客户端缓存提供。

package/docs/PLUGIN_STARTUP.md

@@ -1,8 +1,10 @@
-# Core 启动与插件启用（0.3 alpha）
+# Core 启动与插件启用（0.3 beta）
 
 仅需媒体创作或首次连接 Agent 时，可先走 [Core 快速开始](CORE_QUICKSTART.md)；本页说明如何额外启用可信插件，不必先编写 Node 启动脚本。
 
-使用0.3.0-alpha.1或当前源码；**稳定 npm 0.2.7 没有这些插件启动参数。** 本地安装可在下文 `dsh-iris` 前加 `npx`，源码树可替换为 `node bin/dsh-iris.js`。
+开发自己的独立插件可从[模板与包外验收](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 继续运行。
 
@@ -51,6 +53,17 @@ dsh-iris web serve --data-root /absolute/iris/core \
 
 正常 Ctrl+C 退出后，可以原样重复启动命令。保持同一数据根、固定端口、连接目录和所需准确插件版本，已经导出的 MCP 连接继续有效。不要同时启动两个管理同一根的执行服务；冲突会报忙，不抢锁。强制退出后的租约恢复仍须先核对进程，再按 [Core 服务](CORE_SERVICE.md)的明确命令处理。
 
+## 查看插件状态（当前源码）
+
+此页入口从 **0.3.0-beta.1** 提供；登录后打开侧栏“插件”：
+
+- 插件卡片列出准确身份、版本和 Core 兼容范围，展开后查看模型协议、业务操作、页面、设置与预览贡献。加载时通过兼容校验不代表模型或业务已经实测。
+- 业务是否被服务启用、页面是否选入工作台，分别取自 Core 的实际装配；加载代码不等于授权。
+- 客户端授权区分准确版本不一致、服务未启用、缺少执行权限、未选 `plugin_call` 和已撤销；“授权允许执行”只描述配置条件。握手实例可能请求更小的范围，握手记录也不证明客户端持续在线。
+- 原授权所需的业务未加载时保留准确依赖和原因，不会自动改成新版本或移除原记录。授权读取失败显示“未知”，不会冒充零授权；重新读取只访问现有只读接口，不调用业务或探测模型。
+
+“管理客户端授权”打开已有连接设置。此页不编辑启动文件、安装插件或热加载代码；启用仍按下方选择文件，在正常停止后重新启动服务。若启动失败、服务尚未运行，请在启动终端核对 `code`、`stage`、`file` 和可能的 `field`，也可对确认可信的插件运行 `plugins inspect`；页面无法读取一次尚未启动服务的失败。
+
 ## 选择文件
 
 | 字段 | 含义 |

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`。面向 0.3 的0.3 alpha源码另提供[实例级 Provider 扩展首版](PROVIDER_EXTENSIONS.md)，经实验性窄入口显式加载可信协议；这不代表完整 SDK 冻结。生图模型可通过可选 `imageProtocol` 覆盖账号默认；选择、实测与 Task binding 共用有效协议，详见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议)。未知的显式 `mediaProtocol` 保留原值，未注册时在联网前拒绝；错误只包含合法协议标识，不回显端点或凭据。
+已发布版本的协议工厂由内部注册表选择；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

@@ -1,10 +1,10 @@
-# Provider 扩展首版（0.3 alpha）
+# Provider 扩展首版（0.3 beta）
 
-源码支持实例级媒体协议注册及显式加载可信扩展。**公开 npm 0.2.7 尚不包含此入口**；下列命令用于当前源码或由其生成的候选包。`@mokuyoaxis/dsh-iris/provider-extensions` 是实验性 v0 窄入口，不是完整 Core SDK，也未承诺长期兼容。
+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 和存储规则保持。
 
-源码另提供 [Core 插件贡献 v0](PLUGINS.md)：Provider、业务操作、Web 页面/作品渲染器共用身份、兼容、生命周期和依赖描述。新入口为程序化 `plugins` SDK；本页的工厂及 CLI 参数继续保留。新插件 Provider 的 Task/Attempt 记录准确依赖并纳入 binding，旧扩展的无插件绑定保持；Web 挂载与动态 MCP 装配尚未接入。
+alpha.1 另提供 [Core 插件贡献 v0](PLUGINS.md)：Provider、业务操作、Web 页面/设置及作品渲染器共用身份、兼容、生命周期和依赖描述。新入口为程序化 `plugins` SDK 和[显式启动配置](PLUGIN_STARTUP.md)；本页的工厂及 CLI 参数继续保留。插件 Provider 的 Task/Attempt 记录准确依赖并纳入 binding，旧扩展的无插件绑定保持；Web 按明确选择挂载，MCP 从实际目录和用户授权装配，不因加载插件自动扩权。
 
 ## 显式使用
 
@@ -29,6 +29,10 @@ node bin/dsh-iris.js web serve \
 
 扩展注册不授予模型用途或 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 会缓存模块，模块顶层应保持无实例状态，资源由工厂实例持有。
@@ -75,4 +79,4 @@ Core 会对错误与健康证据中的连接 Key 再做精确脱敏，`auth:none
 
 源树的 `tests/provider-extensions.mjs` 覆盖实例隔离、协议描述、旧哈希、冲突/版本、在途释放与失败。`scripts/verify-provider-extensions-package.mjs` 将候选包解到仓库外，复制独立测试插件包，只经上述公开入口接入真实 CLI/API/Core；受控 HTTP Provider 验证原 Task 恢复、原图编辑、Key 接回和图片字节。
 
-验证脚本明确复用已有依赖，不代表重新安装全部依赖或真实供应商付费验收；测试插件和验收脚本不进入 npm 包。0.3 alpha源码另有 [C3 管理 API/页面](PROVIDER_SETTINGS.md)和独立 [Panel/主题](PANEL_EXTENSIONS.md)；外部凭据桥、任意 Recipe/工具注册与完整插件市场仍是后续工作。
+验证脚本明确复用已有依赖，不代表重新安装全部依赖或真实供应商付费验收；测试插件和验收脚本不进入 npm 包。0.3 beta另有 [C3 管理 API/页面](PROVIDER_SETTINGS.md)和独立 [Panel/主题](PANEL_EXTENSIONS.md)；当前源码支持上述显式环境引用，其他凭据来源桥、任意 Recipe/工具注册与完整插件市场仍是后续工作。

package/docs/PROVIDER_HEALTH.md

@@ -4,7 +4,7 @@
 
 工作台的“能力状态与检测”与 [功能模型池](FUNCTION_MODEL_POOLS.md) 配套；以下健康证据规则继续适用。
 
-**未发布 Core 工作台补充：** 独立[模型服务页](PROVIDER_SETTINGS.md#健康检测与保活)增加六色光谱、模型池排序、连接检查，以及本次 Core 服务内显式开启的轻量保活。连接检查/保活只读取目录或 ComfyUI 服务状态，不写成媒体实测成功；默认关闭，重启不续开。实际验证先打开指定模型草稿，用户点击创作按钮后复用持久任务执行；真实媒体成功受理/同步完成写入对应连接与模型的健康证据。以下“不做定时探测”描述 npm 0.2.7/DSH 的行为，不包含这一未发布且默认关闭的连接保活。
+**0.3 beta Core 工作台补充：** 独立[模型服务页](PROVIDER_SETTINGS.md#健康检测与保活)增加六色光谱、模型池排序、连接检查，以及本次 Core 服务内显式开启的轻量保活。连接检查/保活只读取目录或 ComfyUI 服务状态，不写成媒体实测成功；默认关闭，重启不续开。实际验证先打开指定模型草稿，用户点击创作按钮后复用持久任务执行；真实媒体成功受理/同步完成写入对应连接与模型的健康证据。以下“不做定时探测”描述 npm 0.2.7/DSH 的行为，不包含这一默认关闭的连接保活。
 
 ## 工作台检测入口
 
@@ -45,7 +45,7 @@ Iris 用持久化证据描述“当前配置是否存在、最近是否实际成
 
 ## 什么会改变状态
 
-显式“模型实测”和正常媒体任务会产生持久证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。媒体成功受理/同步完成及显式视觉实测会刷新绿色及其成功时间。0.3 alpha源码中，普通看图、定位、OCR 与纯画面摘要成功不再改写供应商配置；明确模型不存在、限流等已知失败仍按原规则记录。主动音轨转写另行创建媒体任务，其证据继续保存。
+显式“模型实测”和正常媒体任务会产生持久证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。媒体成功受理/同步完成及显式视觉实测会刷新绿色及其成功时间。0.3 beta中，普通看图、定位、OCR 与纯画面摘要成功不再改写供应商配置；明确模型不存在、限流等已知失败仍按原规则记录。主动音轨转写另行创建媒体任务，其证据继续保存。
 
 Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请求或费用。网络错误、5xx、内容安全、用户取消和受理未知不会覆盖近期成功证据。移除 API Key 后回到灰色。
 
@@ -62,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

@@ -1,6 +1,10 @@
-# Core 供应商、模型池与健康检测（0.3 alpha）
+# Core 供应商、模型池与健康检测（0.3 beta）
 
-此页描述0.3.0-alpha.1的配置界面，**稳定 npm 0.2.7 不包含该入口**。它管理 Iris 媒体供应商；harness 接入权限仍在连接中心管理，各家聊天模型登录与 OAuth 不由此页接管。
+此页描述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检测不代替下面的目录、认证或媒体验证。
 
 ## 开启管理
 
@@ -25,14 +29,14 @@ node bin/dsh-iris.js web serve --data-root /absolute/existing-flow-root \
 “模型服务”分为供应商、功能模型池、健康检测三个入口。供应商先显示名称、地址、模型数和配置状态的概览卡片，按六色鸢尾使用极浅点缀；“已配置”不代表实测通过。点击服务卡片或“添加服务”进入编辑，连接、模型与用途、ComfyUI工作流分组显示。顶部返回与底部取消使用同一草稿确认，未保存修改可保留或明确放弃；保存结果未确认时，先重新读取核对。隐藏分组中的必填连接字段无效时，会显示该分组并定位字段。
 
 1. 从“模型服务”或创作区“管理模型”进入，选择卡片或“添加服务”。选预设/自定义，填写名称、Base URL 和认证；高级连接设置默认折叠。稳定 ID 自动生成，不作为日常重命名入口。
-2. 现有 Key 只显示存在状态，不回显。明确选择保留、填写/替换或清除；服务实际不要求认证时可选“无需认证”，保留的旧 Key 不发送。
+2. 现有 Key 只显示存在状态，不回显。明确选择保留、填写/替换或清除；当前源码也可选择环境变量引用并查看就绪状态。服务实际不要求认证时可选“无需认证”，保留的旧 Key 不发送。
 3. 可以先仅保存连接，再主动读取目录；目录只使用已保存连接。也可直接手填模型 ID。
 4. 勾选图片/视频/语音/音乐/转写/视觉用途再保存。新勾选用途时，原本停用的对应功能会改为自动选择，摘要明确列出。已有自动/手动设置不因打开页面而改变。
 5. 返回列表，进入“功能模型池”独立选择自动、手动排序或停用。手动勾选模型后可上移/下移，按显示顺序保存；取消可放弃未保存的池设置。自动和手动均沿用运行时的协议、连接、限流与模型可用性过滤，按顺序优先选择，不是跨请求轮询。手动空池不回落到自动。
 
 目录结果暂存在页面，搜索/加入草稿不写配置、不批准用途。目录元数据与实际协议支持不同；标注用途后运行时仍验证协议、限流和可用性。模型级图片/音乐协议在折叠项中选择：图片可沿用供应商默认，音乐必须明确选择，空值不回落到供应商默认。`gemini-web-music` 的显示名称统一为“Chat Completions（内嵌音频）”，不限定供应商或模型名称，详见[音乐接口](MUSIC.md)。
 
-当前 Core Web/MCP 支持图片生成/编辑及新 v3 根上的语音合成/转写；视频、音乐、视觉可在此页配置用途，但尚未进入这些新创作入口，继续使用已有 DSH/CLI 能力。配置用途、接口支持和创作入口覆盖是不同事实。
+beta.1 的 Core Web/MCP 支持图片生成/编辑、v3/v4 根的语音合成/转写，以及新v4根的[文生视频](VIDEO_FLOWS.md)；音乐/视觉可配置用途，创作继续使用已有DSH/CLI入口。配置用途、接口支持和创作入口覆盖是不同事实。
 
 ComfyUI 预设提供已有服务地址和默认折叠的 API 图/Iris v0/v1 模板导入。每份工作流作为一个明确的图片模型，绑定正向提示词、输出和可选尺寸节点；可勾选已有标量、命名参数并预览表单。导入不执行，同名替换明确确认，加入草稿并保存后才能从创作页选择。目录检查只验证服务并列出已配置工作流，不把远端 checkpoint 自动当成可调用工作流。流程与限制见 [ComfyUI 入口](IMAGE_GENERATION.md#comfyui-入口)。
 
@@ -42,7 +46,9 @@ ComfyUI 切回“自定义兼容服务”会恢复本次编辑中先前的 API
 
 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，应保存在当前用户控制的私有位置。
+连接/模型保存与独立模型池保存均复用原锁、revision 摘要、0600 备份与原子写入。未改动供应商、模型与额外字段保留。原模型可清空用途，新模型可撤销添加。内联配置及其备份仍含 Key；环境引用只保存名称，但切换前的旧备份可能仍含内联 Key，应保存在当前用户控制的私有位置。
+
+环境引用的 owner 投影另返回 `apiKeyEnv` 名称和 `credentialStatus:"ready"|"missing"|"invalid"`；`hasCredential` 表示当前值是否就绪，不回显值，`auth:none` 的可用性独立判断。
 
 设置 `revision` 是不透明的编辑版本：账号、凭据、模型、分配或其他配置变化仍冲突，单纯的健康时间与目录缓存更新不作编辑冲突。保存基于最新配置合并，并在锁内复核原文件字节，保留已有的健康证据；不能用该 revision 替代文件摘要或跳过写入锁。
 
@@ -80,6 +86,6 @@ Core 参数表单与 `POST /api/v0/provider-management/workflow-check` 已接通
 | 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"}`，拒绝额外秘密字段。`assignments` 只含本次修改的能力，值为原有 `{mode:"auto"|"manual"|"disabled",models:[...],hostVision?:boolean}`，不创建第二套格式。
+`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)通过实例描述进入页面；页面不能安装或加载代码。环境凭据引用、DSH 来源桥（C3c）仍未实施。
+未开启 405、连接越权 403、revision 冲突/锁占用 409、非法设置 400、正文过大 413。已加载的 [Provider 扩展](PROVIDER_EXTENSIONS.md)通过实例描述进入页面；页面不能安装或加载代码。当前源码的环境凭据未就绪会在显式目录/连接检查时返回409及 `IRIS_PROVIDER_CREDENTIAL_UNAVAILABLE`；其他外部凭据来源桥继续后续。

package/docs/PROVIDER_SUBMISSION_CONTRACT.md

@@ -51,7 +51,7 @@ Provider `submit()` 必须返回以下四种结构之一：
 
 错误记录不得包含 `cause`、stack、请求体、响应正文、API Key、Authorization、POSIX/Windows 私有绝对路径或签名 URL。调用方可以在当前进程中保留原始异常用于调试，但不得把它当作 Task/Attempt JSON 或事件载荷。
 
-## 上游响应与交付限额（0.3 alpha）
+## 上游响应与交付限额（0.3 beta）
 
 内置 HTTP 媒体传输按实际响应累计字节，不仅依赖 Content-Length；chunked 或压缩解码后的正文同样计数。元数据/错误 JSON 最多 2 MiB，含内嵌媒体的成功 JSON 最多 128 MiB；产物限额为图片 64 MiB、音频 128 MiB、文本 8 MiB、视频 1 GiB。超限中止读取，下载临时文件在原收尾路径清理，不替换既有目标；超时和取消规则继续适用。这是单个响应/产物限额，不是作品库自动配额或 GC。
 
@@ -64,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#可选输入准备与上传边界)。

package/docs/ROADMAP.md

@@ -4,7 +4,7 @@ Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用
 
 ## 当前状态
 
-本文对应 **Iris 0.3.0-alpha.1**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，保留DSH插件与独立CLI，新增Core Web、通用MCP与显式插件贡献，详见 [alpha发布说明](releases/0.3.0-alpha.1.md)。稳定通道0.2.7与其[历史说明](releases/0.2.7.md)保留。
+本文对应 **Iris 0.3.0-beta.1**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，保留DSH插件与独立CLI，新增Core Web、通用MCP与显式插件贡献，详见 [beta发布说明](releases/0.3.0-beta.1.md)。稳定通道0.2.7与其[历史说明](releases/0.2.7.md)保留。
 
 - 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
 - 持久图片导入与原生 Qwen 改图；六类功能可选自动池、手选或停用，宿主视觉需明确启用。0.2.5 建立的 12 个准确 DSH 版本范围保持。
@@ -14,7 +14,7 @@ Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用
 - 提示词的忠实整理、明确改写、可选建议与预览；完整同步媒体结果缓存后的交付恢复。
 - 工作台全媒体筛选、分页、跨页选择和下载，CLI 的配置、查询与可恢复维护。
 
-DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视觉和提示词预览不自动创建媒体任务；Core与Model Port仍是内部契约。Node.js最低22.0.0。0.2.5恢复旧宿主的当前功能，并覆盖12个准确DSH版本；具体版本和历史范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。
+DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视觉和提示词预览不自动创建媒体任务；Core与Model Port仍是内部契约。Node.js最低22.1.0。0.2.5恢复旧宿主的当前功能，并覆盖12个准确DSH版本；具体版本和历史范围见 [兼容矩阵](DSH_COMPATIBILITY.md)。
 
 宿主兼容继续集中在Adapter与客户端桥接。后续DSH更新优先检查实际API、工具/附件交付和输入区契约，复用同一验收入口扩充版本矩阵，避免让旧用户长期停留在缺少新功能的Iris分支。
 
@@ -26,7 +26,7 @@ DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视
 
 [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 不执行步骤，本地创建也不生成；0.3 alpha源码的有限执行、本地停止、Operation 与持久选择见 [API 契约](LOCAL_API_CONTRACT.md)。
+0.2.7 已有 [I4A 默认只读 API](LOCAL_API.md)与 [I4B 本地创建](LOCAL_CREATION.md)：显式回环监听、Bearer/Host/Origin、受控图片，以及新空根主动启用的上传/Run 创建和持久 Key 身份接回。GET 不执行步骤，本地创建也不生成；0.3 beta的有限执行、本地停止、Operation 与持久选择见 [API 契约](LOCAL_API_CONTRACT.md)。
 
 源码树保留 [独立 Web Demo](WEB_PROTOTYPE.md)，只消费演示数据、不调用模型、不计费。真实工作台已迁入其创作/作品/连接结构，新增 [供应商设置](PROVIDER_SETTINGS.md)与 [Panel/外观](PANEL_EXTENSIONS.md)；Demo 内存草稿不导入 Core。本次先按alpha范围交付，真实上游、更多设备与媒体入口继续按实际验证推进。
 
@@ -34,11 +34,11 @@ DSH与CLI共用Task和Artifact，同一数据根只允许一个写者。纯视
 
 0.3 alpha提供 [Core 插件贡献契约](PLUGINS.md)、统一目录、接入预设和默认 Panel 三处组合挂载。[多图对照板](CONTACT_SHEET.md)现已通过公开接口贯穿真实业务、持久 Operation/原 UUID、Web 选择、MCP和包外消费者；验证重启/强杀、缺失/准确版本、缩权及原作品读取。后续按实际反馈完善启用/分发体验和媒体覆盖，不把显式程序化装配称为插件市场。契约仍为实验性，RC与稳定版时间尚未确定。
 
-**0.3 alpha源码进展**：[Core 工作台](LOCAL_WEB.md)已有创作、作品、连接与供应商页面；按独立开关提供改图、有限观察/本地停止、版本约束选择、原字节下载、真实筛选及 owner 配置管理。[Core 服务](CORE_SERVICE.md)提供 Operation、单根 runner 与授权桥；[原请求恢复](WEB_RECOVERY.md)重连只读、不自动首次执行。默认媒体权限仍只读，独立凭据来源和其他媒体继续推进。npm 0.2.7 尚不含这些新入口。
+**0.3 beta进展**：[Core 工作台](LOCAL_WEB.md)已有创作、作品、连接与供应商页面；按独立开关提供图片、语音/转写、有限观察/本地停止、版本约束选择、原字节下载及 owner 配置管理。[Core 服务](CORE_SERVICE.md)提供 Operation、单根 runner 与授权桥；[原请求恢复](WEB_RECOVERY.md)重连只读、不自动首次执行。beta.1新增新v4根的固定文生视频、凭据引用、出口与调度；候选范围见[beta约定](BETA_SCOPE.md)，不自动迁移旧根。npm 0.2.7 尚不含这些Core新入口。
 
-连接名目采用用户建档和 MCP 客户端声明，不扫盘或按品牌白名单限制。源码已支持纯数据模板导入及按连接有效工具交付 Skill，复用显式安装器；下一步完善真实 Web 创作和全媒体分组。客户端身份声明与媒体实测分别展示。
+连接名目采用用户建档和 MCP 客户端声明，不扫盘或按品牌白名单限制。源码已支持纯数据模板导入及按连接有效工具交付 Skill，复用显式安装器；后续继续完善接入体验和尚未接入的媒体分组。客户端身份声明与媒体实测分别展示。
 
-[通用 MCP](MCP.md)已有 stdio/Streamable HTTP、generic 默认连接、明确功能/工具范围和配置导出，支持固定图片编辑及独立文生图；新 v2 根与 [ComfyUI 入口](IMAGE_GENERATION.md)已提供受控验证。新 v3 根另完成 [TTS/转写闭环](AUDIO_FLOWS.md)，包括Web播放/文本/下载、原任务恢复和MCP可选分组。后续按现有 Core 的真实受理/恢复/交付能力逐组接入视频、音乐和视觉；音频真实供应商与设备验收仍待完成，不因客户端连接成功就视为全媒体已覆盖。
+[通用 MCP](MCP.md)已有 stdio/Streamable HTTP、generic 默认连接、明确功能/工具范围和配置导出，支持固定图片编辑及独立文生图；新 v2 根与 [ComfyUI 入口](IMAGE_GENERATION.md)已提供受控验证。新 v3 根另完成 [TTS/转写闭环](AUDIO_FLOWS.md)，包括Web播放/文本/下载、原任务恢复和MCP可选分组。beta.1的新v4根已接入[固定文生视频](VIDEO_FLOWS.md)及标准MCP资源读取；Core持久音乐/视觉流程仍待后续，既有DSH/CLI能力分别保留。受控测试、真实供应商和设备验收分别记录，不因客户端连接成功就视为全媒体已覆盖。
 
 [DSH ComfyUI 专区](IMAGE_GENERATION.md#dsh-工作台入口03-alpha)已接通现有供应商、画图与泡泡卡片，提供参数模板和只读节点检查；仍使用宿主原 Task，固定 Flow 尚未进入 DSH 面板。独立 Core 已补 v1 导入/表单预览、LoRA 双权重等参数及原 Run 参数查看；工作流卡片/预设、真实 GPU 与远程部署验收继续后续推进，官网/源码与受控浏览器验证不等于推理验收。
 

package/docs/SECURITY.md

@@ -37,7 +37,7 @@ API、SSE 和 Doctor 只返回凭据存在性或掩码提示。Provider 错误
 ## 文件、上传与媒体访问
 
 - 浏览器上传使用大小上限、随机文件名、`.part` 临时文件和完成后的原子改名；中断时清理临时文件，过期副本按 TTL 回收。
-- 输出文件名由 Iris 生成或通过 `basename` 收口，API 不返回宿主绝对路径。
+- 正常输出使用Iris生成的受控文件名，状态和作品列表不返回数据根路径。DSH上传接口按设计返回临时文件绝对路径，显式 `attachment_export` 也返回本地导出路径；这些本机调用结果不等于所有API都禁止绝对路径。独立Core API的媒体输入继续使用原字节或Artifact ID，不接受任意服务器路径。
 - legacy 任务与独立作品的媒体链接使用随机 128-bit 能力令牌。令牌应视为临时访问凭据，不应发布到公网。
 - Core 媒体路由 `/iris/api/core/artifact/<artifact_id>/media` **没有独立 token**。它使用随机 96-bit Artifact ID 作为不可猜测的持有者标识，并叠加默认回环/显式 trusted Host、浏览器 `Origin`/`Sec-Fetch-Site` 拒绝跨站、`Cross-Origin-Resource-Policy: same-origin`、`Referrer-Policy: no-referrer` 与每次 SHA-256 校验。任何能访问受信 Host 且持有 Artifact ID 的客户端都能读取对应媒体；`IRIS_TRUSTED_HOSTS` 不是身份认证。不要把 Core Artifact ID 或媒体 URL 发布到不受信任位置。
 - 清理任务元数据默认不删除作品；legacy 独立作品索引不保存 Prompt、Provider、Model 或任务关系；Core Manifest 保存中性元数据、SHA-256 和来源/派生关系，不保存凭据或私有下载 URL。

package/docs/SYNC_DELIVERY_RECOVERY.md

@@ -2,7 +2,7 @@
 
 Iris 0.2.3 支持从缓存恢复完整同步媒体结果。本地交付失败后，可沿原任务重新交付；Task/Artifact 格式和公开 HTTP 路径保持，不需要迁移旧数据。
 
-未发布的 [固定图片流程](IMAGE_FLOW.md)也将其绑定任务的成功 poll 结果先写入原交付缓存，再按预留 Artifact ID 交付；相应中断只接回原结果，不重新 submit。未绑定 Flow 的异步 Task 沿用原路径，本节其余内容描述 0.2.3 起的同步恢复边界。
+[固定图片流程](IMAGE_FLOW.md)也将其绑定任务的成功 poll 结果先写入原交付缓存，再按预留 Artifact ID 交付；相应中断只接回原结果，不重新 submit。未绑定 Flow 的异步 Task 沿用原路径，本节其余内容描述 0.2.3 起的同步恢复边界。
 
 ## 使用行为
 
@@ -28,6 +28,10 @@ dsh-iris task redeliver task_0123456789abcdef01234567 \
 
 URL 下载只有正常完成、实际文件大小与 Adapter 返回值一致并通过媒体类型检查后，才提交包含 size/SHA-256 的 payload 引用。未提交文件不冒充完整缓存；已提交字节在每次恢复时重新校验。缓存已提交但 Task 完成事实尚未落盘时，显式 Task 恢复可从同一 Attempt 的缓存补回成功事实，然后将中断交付置为 failed，等待用户显式重新交付。
 
+beta.1修复统一按 Task 能力检查交付大小：图片64 MiB、TTS/音乐128 MiB、转写8 MiB、通用视频1 GiB。内联Base64在解码和写payload前按实际解码长度检查；恢复旧缓存和接收Adapter文件时，在哈希或图片整读前检查实际文件大小，不按上游声称的MIME放宽限额。这些是单件作品限额，固定视频Flow的32 MiB边界另见[视频流程](VIDEO_FLOWS.md)。
+
+超限仍保留 `accepted / succeeded / deliveryState=failed` 的生成事实及原Attempt，不转为生成失败或重提候选。若超限导致完整缓存未能发布，同步结果不能据此离线补交付；已有远端ID的任务保留原ID，后续显式取回仍受相同限额。未提交或旧的超限缓存保留现场，不自动清理。
+
 Artifact 写入采用缓存预留的 ID。已有完整对象、Manifest 或提交 Record 必须与恢复的内容和中性元数据一致；异常证据保留并拒绝覆盖。第一件作品成功而第二件失败、或作品全部提交而 Task ready 落盘失败时，恢复复用已提交作品，不创建重复 ID。reader、Doctor、查看任务和刷新作品均不触发恢复。
 
 该机制不保证在收到响应与成功保存缓存之间断电/进程退出时仍能找回结果；磁盘写入失败也可能使完整结果无法缓存。缓存发布失败仍保持已生成的 succeeded/failed 事实，不据此自动重提。旧同步失败任务没有保留下来的结果时，不能追溯恢复。签名 URL 过期后也不能保证下载可继续。