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

package/docs/PLUGINS.md

@@ -0,0 +1,189 @@
+# Core 插件贡献 v0（0.3 alpha，实验性）
+
+0.3.0-alpha.1 提供实验性 `@mokuyoaxis/dsh-iris/plugins` 入口及类型声明。**稳定 npm 0.2.7 没有这个入口**；示例用于alpha包或当前源码，尚未承诺稳定 SDK。兼容检查读取实际包版本，alpha标识也参与SemVer先后比较。
+
+## 贡献与装配
+
+一个插件可组合以下贡献；它们由同一实例激活和释放。
+
+| 清单字段 | 当前已有行为 | 后续装配 |
+|---|---|---|
+| `providers` | 桥接已有 Provider 注册器，复用媒体任务执行、目录与恢复 | 沿用显式 Provider 配置，仍只有既定五种媒体任务能力 |
+| `operations` | 声明输入、模式与 Core 命令；本地 Host 调用或明确选入持久 `plugin.execute`，经 Web/通用 MCP 使用 | 尚无 CLI 业务执行命令或插件安装向导 |
+| `pages` | 显式选入默认工作台导航，共享主题、登录与受控 Core API；业务需服务主动开启 | 无自动安装或发现 |
+| `settings` | 默认折叠的设置模块；管理开启时复用 Core Provider 读写 | 暂无任意插件私有设置存储 |
+| `renderers` | 按实际媒体类型列出可选预览，读取原始 Artifact | 新媒体类型仍受 Core 实际交付接口限制 |
+
+插件实现业务；Core 管权限、执行队列及存储；Web/MCP 再交付能力，Skill 解释使用方式。注册不会创建 MCP 授权、修改 harness、调用模型或把任意代码暴露为 API。`activate` 与模块顶层仍是可信代码，应只初始化自己的资源，不提交媒体任务。
+
+[原 Provider 扩展](PROVIDER_EXTENSIONS.md)和[整套 Panel 替换](PANEL_EXTENSIONS.md)继续可用，入口格式分别保留。CLI 的 `--provider-extension` 接收原 Provider 工厂，`--panel` 接收整套资源清单；不要把新插件清单直接传给这两个参数。CLI 可用[显式插件启动配置](PLUGIN_STARTUP.md)装配，Node 宿主也可使用下方公开接口。
+
+## 最小业务插件
+
+```js
+import { definePlugin } from '@mokuyoaxis/dsh-iris/plugins';
+
+export default definePlugin({
+  manifest: {
+    contractVersion: 0,
+    id: 'example.library',
+    version: '1.0.0',
+    compatibility: { min: '0.3.0-alpha.1', maxExclusive: '0.4.0' },
+    contributions: {
+      operations: [{
+        id: 'count', version: '1.0.0', title: 'Count saved artifacts',
+        mode: 'reader', commands: ['artifact.list'],
+        inputSchema: { type: 'object', properties: {}, required: [], additionalProperties: false }
+      }]
+    }
+  },
+  activate({ onDispose }) {
+    // Register cleanup before awaited initialization, so failed activation also releases it.
+    onDispose(async () => { /* release resources owned by this instance */ });
+    return {
+      operations: {
+        async count(_input, { core }) {
+          const result = await core.execute('artifact.list', {});
+          return { count: result.total };
+        }
+      }
+    };
+  }
+});
+```
+
+`min` 从首次提供此SDK的0.3.0-alpha.1开始，稳定0.2.7不支持插件入口。Core兼容区间使用闭/开边界，npm peer范围另按npm SemVer规则处理；面向本alpha的插件可明确声明 `>=0.3.0-alpha.1 <0.4.0`，不能假定仅有稳定版下界的范围会接受预发布。
+
+宿主显式加载已安装且可信的 JS/MJS 入口；示例使用已经存在的 Core 数据根，只读调用不会创建它：
+
+```js
+import { loadCorePluginRegistry, createCorePluginHost } from '@mokuyoaxis/dsh-iris/plugins';
+
+const registry = await loadCorePluginRegistry({ entries: ['/absolute/my-plugin/index.mjs'] });
+const host = createCorePluginHost({
+  dataRoot: '/absolute/existing-core', registry,
+  allowedOperations: ['example.library.count']
+});
+try {
+  const result = await host.call('example.library.count', {});
+  console.log(result); // { dependency: ..., value: { count: ... } }
+} finally {
+  await host.dispose();
+  await registry.dispose();
+}
+```
+
+`createCorePluginRegistry({plugins:[definition]})` 用于已有模块的显式装配；默认 Core 版本来自实际包。`coreVersion` 仅供具体宿主装配或兼容测试显式传入，不应用虚构版本绕过兼容检查。Host 关闭不释放共享 registry；先关闭全部使用者，再释放 registry。
+
+## Core 能力目录与授权
+
+内置工具的名称、输入、功能归属、操作权限和逐工具使用说明集中在 Core 声明中。MCP/DSH 工具定义、连接校验、Web 连接选项、会话操作投影和连接专属 Skill 从它派生。工作流配方、图标和人工解释仍可单独编写；它们不能增加可调用能力。历史授权仍保存准确工具名单，旧文件的固定兼容集合保持，不因新增工具或安装插件自动扩张。
+
+公开目录只读取已校验注册器，既不扫描模块，也不调用业务：
+
+```js
+import { createCoreCapabilityCatalog } from '@mokuyoaxis/dsh-iris/plugins';
+
+const catalog = createCoreCapabilityCatalog({ registry });
+const declared = catalog.snapshot({ audioEnabled: true });
+// groups/tools/scopeOptions/media：Core 内置连接选项。
+// plugins/contributions：已加载插件和五类贡献的身份、版本、准确依赖及接入状态。
+const selected = catalog.selectOperations(['example.library.count']);
+// 仅校验装配者明确提供的本地选择；不调用、不持久授权、不开放 Web/MCP。
+```
+
+`audioEnabled` 仅决定目录显示哪些内置分组，不能开启工作区或绕过真实根版本检查。目录快照深度只读；省略 `registry` 时仅列内置选项和空插件贡献。`selectOperations()` 默认空，未知或重复业务拒绝；注册器关闭后贡献标为 unavailable，不能继续选择。程序化 Host 也通过此目录校验 `allowedOperations`，真实调用继续检查原贡献依赖、输入和 Core 队列权限。
+
+贡献的 `access` 是装配边界，**不是用户已经授权或服务已实测**：Provider 的 `via-media-flow` 仍需模型配置和流程授权。业务默认尚未暴露；服务明确选择 `allowedOperations` 后，Web/MCP 状态才成为 `via-operation/requires-selection`，连接还需选择准确依赖。Web 贡献默认 descriptor-only / not-mounted；选入后为 available-in-panel，不表示已加载或实测。发现接口不提供脚本路径；选中模块的固定 URL 只在 owner 工作台会话中交付。
+
+源码服务装配器可显式给 `createLocalReadApi` 传入同一 `pluginRegistry`、`panelContributions` 和 `allowedOperations`；若另传 `providerRegistry`，须是该实例的 `registry.providers`。先关闭全部服务与 Host 再释放共享注册器。owner 能力/连接管理目录读取同一投影，连接凭据只能读自身业务选择。包外可用下方公开入口，或 `api/web serve --plugin-config`；CLI 持有并按服务 → 注册器顺序释放资源。
+
+## 身份、版本与兼容
+
+- `contractVersion` 当前为 `0`。插件 `id/version`、各贡献 `id/version` 与 Iris 包版本分别管理。
+- ID 使用有界小写字母、数字、点、连字符或下划线，贡献的公开 ID 为 `pluginId.localId`，合并后最多 80 字符。`iris`/`iris.*` 及现有 Core 命令根名称保留；同插件与同类贡献的完整 ID 不能重复，后加载不能覆盖，包括不同插件/局部 ID 拼接成同一完整 ID 的情况。
+- 插件及贡献版本为 SemVer；同一版本应保持相同实现和持久语义。版本声明不是代码完整性校验或安全签名。
+- `compatibility` 为 `min <= coreVersion < maxExclusive`。使用 SemVer 优先级，构建元数据不影响比较，区间内预发布版本按同一顺序比较；不支持 npm 的 `^`、`~`、`||` 或通配范围。
+- 全部清单、兼容与业务输入 Schema 在任何 `activate` 前检查。动态 `import` 已执行模块顶层，兼容门禁不隔离模块求值。
+- 清单是可序列化数据。模块缓存可复用，实例资源须在 `activate` 内建立；实现映射必须与声明一一对应。
+
+## 业务操作
+
+`mode` 为 `reader/writer`，`commands` 是此贡献要调用的 Core 命令子集。Host 的 `allowedOperations` 默认空，捕获后单次调用不能扩大。命名空间与声明都不代替用户授权。
+
+允许 `artifact.inspect/read/list`、`task.inspect/list` 和写者使用的 `artifact.import`。`artifact.read({artifact_id})` 返回8 MiB内 PNG/JPEG/WebP 元数据与 `imageBase64`；`artifact.import({image_bytes})` 仅接图片字节。持久业务用可选 `artifactInputs` 声明来源 ID 的顶层字符串/字符串数组字段，只能读取已绑定来源。未声明命令拒绝，读业务不能写。删除、任意路径、shell、远端提交/观察不在子集中；复用 Core FIFO/租约与已落盘读取。
+
+连接选入带图片输入的业务后，目录和预览共享同一根内符合上述格式/大小的图片，包括其他业务产物；来源共享不授予其他业务的执行、历史或停止权限。没有图片输入声明的业务不因此获得图库读取。此规则不隔离同进程原生插件代码；需要作品隔离时使用独立数据根，安装只信任的插件。
+
+输入为封闭根对象的 JSON Schema：支持 `type/title/description/properties/required/additionalProperties/items/anyOf/enum/const`、数字上下界及 `multipleOf`、字符串长度及 `pattern`、数组长度。类型为 object/array/string/integer/number/boolean/null；未知关键字、`$ref`、默认值与隐式转换不接受，受现有 Zod 编译器约束，无法编译会在激活前拒绝。
+
+调用只获得 `{signal, dependency, core:{execute}}`，没有宿主 ctx、Token、数据根或直接存储句柄。Core 命令顺序执行；即使业务忘记 await，Core 也等待所有已发出的命令并报告失败，不提前释放租约。业务输入为独立冻结的 JSON，返回值也必须为 JSON；图片等字节经 Core 导入并返回 Artifact ID。业务自己抛出的意外错误保留给装配者定位。
+
+`host.call` 仍是直接本地调用，没有自动幂等或请求 Key。持久调用由公开工作台的 `allowedOperations` 主动开启，经同一 runner 保存 `plugin.execute`，再由 Web 或通用 MCP 调用；不能混称两条路径。真实随包业务、装配和恢复语义见[多图对照板](CONTACT_SHEET.md)。
+
+## Provider 贡献
+
+清单项为 `{id,version,title,capabilities,configuration?}`。能力与配置字段沿用原 Provider 约束。`activate` 返回同名 `providers` 映射，每项实现 `normalizeEndpoint/createAdapter`，可选 `supportsModel/supportsImageEdit`；具体调用继续遵守 [Provider Adapter](PROVIDER_ADAPTER_CONTRACT.md)。
+
+协议 ID 由 Core 设为完整贡献 ID。Adapter 的配置身份仍为用户的 Provider ID；Core 覆盖并验证协议/依赖元数据，插件不能通过描述更改配置身份。`registry.providers` 是已有注册器形状，可显式传给使用 `providerRegistry` 的服务；该方式只接入 Provider 部分，不挂载页面或新增工具。Provider 下载沿用 Core 分配的暂存目标，不自行管理作品索引。
+
+## 持久依赖与恢复
+
+统一依赖格式：
+
+```json
+{
+  "contractVersion": 0,
+  "pluginId": "example.media",
+  "pluginVersion": "1.0.0",
+  "kind": "providers",
+  "contributionId": "example.media.images",
+  "contributionVersion": "1.0.0"
+}
+```
+
+`registry.dependency(kind,fullId)` 返回冻结描述，`assertDependency` 核对序列化后原身份。新插件 Provider 在远端提交前，由 Core 将 `pluginDependency` 保存到 Task/Attempt，并把同一依赖加入 Provider binding。配置解析和较低层 Task Runner 都核对依赖；插件/贡献版本改变或缺失时，不观察、不重选、不重新生成。恢复准确版本后，仅明确操作才继续原远端任务。
+
+历史任务及已保存作品在缺少插件时仍可读取。旧 Provider 绑定不加字段、不猜测插件版本、不迁移；旧 Task schema/语义版本保持，可选元数据仅写入新插件产生的 Attempt。Task 与其当前 Attempt 的依赖不一致视为记录损坏。首片不提供兼容恢复别名、自动迁移或热替换，升级失败不会转成重新提交；已有明确计费重试仍按原规则创建新 Task，不冒充原任务恢复。
+
+## Web 贡献和生命周期
+
+页面和设置表单声明 `{id,version,title,entry,styles?}`；作品渲染器再声明非空 `mediaTypes`，使用 `image/png` 等准确值，不接受通配符。入口为插件目录内 JS/MJS，样式为 CSS；不接受 URL、绝对路径、查询、父目录或符号链接逃逸。加载器在激活前固定资源字节，单文件最多 8 MiB，每插件合计最多 16 MiB；浏览器只获得明确选中贡献的入口与样式，不开放插件目录或 Node 入口。入口应打包为独立模块，样式不能依赖未声明文件；不扫描 import 图或自动发布同目录资源。
+
+模块导出 `mount(context)`，可返回清理函数或其 Promise。上下文含 `container/signal/dependency/session/theme/api`，渲染器另有 `artifact:{id,mediaType,label?}`。三处使用同一冻结的会话快照，不提供 Token 字段；`theme.current()/subscribe()` 读取实际明暗和密度，CSS 继承鸢尾及工作台变量。挂载容器位于 Shadow DOM，避免样式意外覆盖工作台。
+
+`api` 复用认证客户端，提供 `runs/run/models/audioModels/artifact`，不接任意 URL/路径。只有设置模块且开启 owner 供应商管理才有 `api.providers.read()/save()`，沿用 revision/凭据动作。持久业务开启时另有 `api.pluginOperations.catalog/history/execute/inspect/lookup/stop`；execute 需要稳定 `key` 和准确 `operationId/dependency/input`，返回持久回执。Core 逐请求核对权限；未知结果查原 UUID，不自动重做。没有任意配置存储或通用命令转发。
+
+挂载器在会话选中 Web 贡献或开启持久业务时加载；旧服务两者均无时不请求新增资源。导航页按需加载；设置默认折叠；预览需展开并选择匹配 MIME 的渲染器，原生预览仍可用。切页、收起或退出会中止信号、撤销对应 API、移除容器/主题监听并清理；迟到挂载仍会释放。插件负责自己的 Blob URL/监听/定时器和未保存草稿。错误显示贡献 ID、阶段及可用关联 ID；重新打开可显式重试，不自动换插件。
+
+包外消费者可以装配已有 Core 根：
+
+```js
+import { loadCorePluginRegistry, createCorePluginWorkbench } from '@mokuyoaxis/dsh-iris/plugins';
+
+const registry = await loadCorePluginRegistry({ entries: ['/absolute/my-plugin/index.mjs'] });
+const web = createCorePluginWorkbench({
+  dataRoot: '/absolute/existing-core', registry,
+  workbenchAuth: { directory: '/absolute/private-auth' },
+  panelContributions: {
+    pages: ['example.library.browse'],
+    settings: ['example.library.connection'],
+    renderers: ['example.library.png']
+  }
+  // Optional: allowProviderManagement: true, providerConfigPath: '/absolute/providers.json'
+});
+try {
+  const started = await web.start();
+  // First start: open started.loginUrl privately to set a password. Later: use the ordinary origin.
+  await new Promise(resolve => process.once('SIGINT', resolve));
+} finally {
+  await web.dispose();
+  await registry.dispose();
+}
+```
+
+此例的三个 ID 需要实际声明，上方最小业务插件没有这些模块。构造不启动服务、不建根或扫盘；显式 `start()` 仅绑定 loopback，嵌入程序负责 dispose。`workbenchAuth` 显式开启[访问口令](WORKBENCH_LOGIN.md)，省略时保持旧 SDK 的一次性链接模式；认证目录须在 Core 根外且私有。默认媒体只读，供应商编辑另行开启。可选 `allowedOperations` 明确业务完整 ID，要求现有专用执行根；省略不装配业务 runner，`[]` 仅接管/读取历史而不接收新业务。`connectionStore` 指定根外私有目录并开启 owner 管理，`allowMcp` 主动开启 HTTP MCP。整套 Panel 替换仍可用 CLI `--panel` 或 `panelManifestPath`，与组合选择互斥。
+
+`activate({coreVersion,plugin,onDispose})` 为每个实例调用一次。初始化资源后及时注册 onDispose，全部关闭时拒绝新业务及 Provider 调用，等待已预约/在途调用，然后逆序释放资源。初始化失败也释放已注册资源；多项清理错误聚合报告，重复 dispose 返回同一结果。Web mount/清理属于浏览器生命周期，不在 Node activate 内执行。
+
+同进程插件有 Node 进程权限，同源 Web 模块有页面脚本权限，可访问浏览器存储和同源接口。窄 API、Shadow DOM、CSP 及不传 Token 字段不能隔离恶意代码，只加载已审查可信模块。安装器/市场、非可信代码隔离、任意副作用的恢复策略与稳定 SDK 冻结仍未完成。

package/docs/PLUGIN_STARTUP.md

@@ -0,0 +1,100 @@
+# Core 启动与插件启用（0.3 alpha）
+
+仅需媒体创作或首次连接 Agent 时，可先走 [Core 快速开始](CORE_QUICKSTART.md)；本页说明如何额外启用可信插件，不必先编写 Node 启动脚本。
+
+使用0.3.0-alpha.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)的明确命令处理。
+
+## 选择文件
+
+| 字段 | 含义 |
+|---|---|
+| `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

@@ -25,7 +25,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 alpha源码另提供[实例级 Provider 扩展首版](PROVIDER_EXTENSIONS.md)，经实验性窄入口显式加载可信协议；这不代表完整 SDK 冻结。生图模型可通过可选 `imageProtocol` 覆盖账号默认；选择、实测与 Task binding 共用有效协议，详见 [模型级图片协议](CLI_MANAGEMENT.md#模型级图片协议)。未知的显式 `mediaProtocol` 保留原值，未注册时在联网前拒绝；错误只包含合法协议标识，不回显端点或凭据。
 
 未配置协议或选择 `auto` 时，官方端点可识别为对应协议；其他端点继续使用 OpenAI Images 兼容路径，并标记 `protocolInferred:true`。该标记表示尚待用户确认兼容性，不代表已经验证成功。显式选择协议会清除标记；旧记录中已保存的明确协议不追溯猜测其来源。CLI 与 DSH 共用选择逻辑，Task binding 绑定最终实际协议与端点。
 

package/docs/PROVIDER_EXTENSIONS.md

@@ -0,0 +1,78 @@
+# Provider 扩展首版（0.3 alpha）
+
+源码支持实例级媒体协议注册及显式加载可信扩展。**公开 npm 0.2.7 尚不包含此入口**；下列命令用于当前源码或由其生成的候选包。`@mokuyoaxis/dsh-iris/provider-extensions` 是实验性 v0 窄入口，不是完整 Core SDK，也未承诺长期兼容。
+
+六类内置协议（含 [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 装配尚未接入。
+
+## 显式使用
+
+扩展通过已安装包的 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，也不需各自加载同一媒体插件。
+
+## 模块契约
+
+默认导出一个工厂，每次创建注册实例会重新调用；工厂可异步返回以下对象。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 alpha源码另有 [C3 管理 API/页面](PROVIDER_SETTINGS.md)和独立 [Panel/主题](PANEL_EXTENSIONS.md)；外部凭据桥、任意 Recipe/工具注册与完整插件市场仍是后续工作。

package/docs/PROVIDER_HEALTH.md

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

package/docs/PROVIDER_SETTINGS.md

@@ -0,0 +1,85 @@
+# Core 供应商、模型池与健康检测（0.3 alpha）
+
+此页描述0.3.0-alpha.1的配置界面，**稳定 npm 0.2.7 不包含该入口**。它管理 Iris 媒体供应商；harness 接入权限仍在连接中心管理，各家聊天模型登录与 OAuth 不由此页接管。
+
+## 开启管理
+
+使用已有私有配置和专用 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)。
+
+当前 Core Web/MCP 支持图片生成/编辑及新 v3 根上的语音合成/转写；视频、音乐、视觉可在此页配置用途，但尚未进入这些新创作入口，继续使用已有 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，应保存在当前用户控制的私有位置。
+
+设置 `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"}`，拒绝额外秘密字段。`assignments` 只含本次修改的能力，值为原有 `{mode:"auto"|"manual"|"disabled",models:[...],hostVision?:boolean}`，不创建第二套格式。
+
+未开启 405、连接越权 403、revision 冲突/锁占用 409、非法设置 400、正文过大 413。已加载的 [Provider 扩展](PROVIDER_EXTENSIONS.md)通过实例描述进入页面；页面不能安装或加载代码。环境凭据引用、DSH 来源桥（C3c）仍未实施。

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 alpha）
+
+内置 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 中安全切换。

package/docs/ROADMAP.md

@@ -4,7 +4,7 @@ Iris 的方向是本地优先、Agent 可调用的多模态创作工作台。用
 
 ## 当前状态
 
-本文对应 **Iris 0.2.7**，发布状态见 [README](../README.md)。包名为 `@mokuyoaxis/dsh-iris`，同时提供 DSH 插件与独立 CLI；本版增加截图修复、实例运行时、持久图片流程、本地 API 和 Core Skill 安装，详见 [0.2.7 发布说明](releases/0.2.7.md)。
+本文对应 **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)保留。
 
 - 图片生成、Artifact ID 看图/OCR/定位和聊天改图，支持按模型配置图片协议。
 - 持久图片导入与原生 Qwen 改图；六类功能可选自动池、手选或停用，宿主视觉需明确启用。0.2.5 建立的 12 个准确 DSH 版本范围保持。
@@ -26,11 +26,21 @@ 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 不执行步骤，本地创建也不生成；有限执行/取消与 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 alpha源码的有限执行、本地停止、Operation 与持久选择见 [API 契约](LOCAL_API_CONTRACT.md)。
 
-源码树保留 [面向 0.3.0 的独立 Web Demo](WEB_PROTOTYPE.md)，用于说明输入、状态、比较与选择的操作方向。当前只消费演示数据，不连接模型、不计费，也未接入 API；界面与交互细节留到 **0.3.0 阶段统一润色**。后续补执行接收、取消和恢复验收，再接入实际工作台。通用 Recipe 与实际独立工作台尚未完成，没有已承诺的发布日期。
+源码树保留 [独立 Web Demo](WEB_PROTOTYPE.md)，只消费演示数据、不调用模型、不计费。真实工作台已迁入其创作/作品/连接结构，新增 [供应商设置](PROVIDER_SETTINGS.md)与 [Panel/外观](PANEL_EXTENSIONS.md)；Demo 内存草稿不导入 Core。本次先按alpha范围交付，真实上游、更多设备与媒体入口继续按实际验证推进。
 
-## 近期优先：真实使用验收
+## 近期优先：插件契约与真实接入
+
+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 尚不含这些新入口。
+
+连接名目采用用户建档和 MCP 客户端声明，不扫盘或按品牌白名单限制。源码已支持纯数据模板导入及按连接有效工具交付 Skill，复用显式安装器；下一步完善真实 Web 创作和全媒体分组。客户端身份声明与媒体实测分别展示。
+
+[通用 MCP](MCP.md)已有 stdio/Streamable HTTP、generic 默认连接、明确功能/工具范围和配置导出，支持固定图片编辑及独立文生图；新 v2 根与 [ComfyUI 入口](IMAGE_GENERATION.md)已提供受控验证。新 v3 根另完成 [TTS/转写闭环](AUDIO_FLOWS.md)，包括Web播放/文本/下载、原任务恢复和MCP可选分组。后续按现有 Core 的真实受理/恢复/交付能力逐组接入视频、音乐和视觉；音频真实供应商与设备验收仍待完成，不因客户端连接成功就视为全媒体已覆盖。
+
+[DSH ComfyUI 专区](IMAGE_GENERATION.md#dsh-工作台入口03-alpha)已接通现有供应商、画图与泡泡卡片，提供参数模板和只读节点检查；仍使用宿主原 Task，固定 Flow 尚未进入 DSH 面板。独立 Core 已补 v1 导入/表单预览、LoRA 双权重等参数及原 Run 参数查看；工作流卡片/预设、真实 GPU 与远程部署验收继续后续推进，官网/源码与受控浏览器验证不等于推理验收。
 
 优先完善图片创作与配乐、短片素材准备等完整流程：复用已有作品、按需生成、试听或查看结果，再导出可继续处理的素材。分别交付音视频素材不等于自动混音成片。
 
@@ -54,14 +64,14 @@ DSH 工作台与 Headless CLI 共用 Core 的可恢复隔离和恢复入口，
 - 有可用接口与实际需求后，补 Images 编辑、mask、多参考图或连续编辑；
 - 在已有纯核心提示词实现上补共享 `prompt.optimize` Command 与 CLI 消费；DSH 负责草稿读取、预览和写回；
 - 冻结中立 TextModel Port，把 Ollama、兼容文本端点及其他文本模型后端与媒体 Provider Catalog 分离，避免通用文本模型淹没 Iris 媒体模型界面；
-- 接入 ComfyUI、本地 TTS 等本地媒体 Provider，并补齐 `auth: none`、`billing: none`、同步完成语义和本地/远程 UI 区分；
+- ComfyUI 原生 HTTP/工作流入口已接入，真实 GPU/节点与部署验证继续单列；本地 TTS、费用标签、更多完成语义和本地/远程 UI 体验按需求推进；
 - 有可信价格来源后的成本与策略展示。
 - 显式授权后的目录新模型跟随、新语音协议及磁盘占用管理；当前自动池不自动授权目录新增模型，也没有跨请求轮转。
 
 ### 0.3 及以后
 
-- `0.3`：Recipe、可恢复 Flow、显式启动的本地 API 和最小独立工作台；
-- `0.4`：在有真实消费者后公开 Provider/Host SDK；
+- `0.3`：可恢复 Flow、本地 API、独立工作台和实验性插件贡献；优先改善 MCP 首次接入及公开贡献的实际消费；
+- `0.4`：根据真实插件/宿主消费者继续完善 SDK，Host 扩展及兼容承诺按验证范围推进；
 - `1.0`：冻结经过多宿主和升级验证的公共契约。
 
 ## 兼容性与限制

package/docs/VISION_CLI.md

@@ -77,7 +77,7 @@ dsh-iris vision summarize \
 
 ## 配置和模型选择
 
-配置沿用 Iris Provider 文件，不执行配置迁移或模型发现。文件必须为普通文件，POSIX 权限限制为当前用户可读写（例如 `chmod 600 providers.json`）。可以直接只读使用已有 Iris 配置；不会推断 DSH_HOME、HOME 或当前目录。
+配置沿用 Iris Provider 文件，不执行配置迁移或模型发现。文件必须为普通文件，POSIX 权限限制为当前用户可读写（例如 `chmod 600 providers.json`）。普通视觉成功保留配置原字节，不持久刷新健康时间；明确模型不存在、限流等失败仍沿用健康记录规则。显式开启音轨转写会创建 Core 媒体任务并保存对应成功证据；这些写入不改变账号、模型或功能分配。不会推断 DSH_HOME、HOME 或当前目录。
 
 最小结构如下，`apiKey` 由你在私有文件中设置，不放在命令参数中：