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

package/docs/LOCAL_WEB.md

@@ -0,0 +1,207 @@
+# 本地 Core 工作台（0.3 beta）
+
+第一次使用可从[空配置快速开始](CORE_QUICKSTART.md)依次完成启动、口令登录、供应商/模型池、首件作品与 MCP 连接。本文保留各独立开关与已有工作区的详细参考。
+
+源码中的 `web serve` 提供独立的总览、创作、作品、连接和供应商页面，使用 [本地 API](LOCAL_API.md) 与固定流程，无需启动 DSH。默认只读；显式开启执行和选择后，可改图、比较、保存选择并下载。新的 v2 执行根另提供[文生图与 ComfyUI](IMAGE_GENERATION.md)，v3 音频根另提供[语音合成和音频转写](AUDIO_FLOWS.md)、播放及文字下载。连接中心分配 MCP 能力；[供应商设置](PROVIDER_SETTINGS.md)管理媒体连接与模型用途，两者单独开启。
+
+**本页入口从0.3.0-alpha.1提供，稳定 npm 0.2.7 不包含。** 以下命令使用源码树；安装beta包后将 `node bin/dsh-iris.js` 换为 `npx dsh-iris`，不能照搬到0.2.7。原 [交互 Demo](WEB_PROTOTYPE.md) 继续保留，两者是不同入口。
+
+界面沿用 Demo 的侧栏、大画布和右侧设置区，默认白色主体，六色 105 度鸢尾渐变作点缀。“外观”提供主题、密度与浏览器本地背景，图片比较区保持中性。高级参数、模型说明、流程详情与连接工具默认折叠。新草稿展开设置，固定输入的 Run 在手机上收起设置；并排、叠图和放大只改变查看方式。默认 Panel 可用显式资源清单替换，见 [Panel 与外观](PANEL_EXTENSIONS.md)。
+
+管理入口显示为“客户端”和“模型服务”：首屏为真实连接/服务概览，点击卡片或新建后进入独立编辑面板。两类编辑页均有顶部返回与底部取消，未保存时可保留或明确放弃。模型服务另分供应商、功能模型池和健康检测，减少编辑页内重复设置；全局池独立保存，支持手动上移/下移。接入帮助和未接入能力默认折叠，手机管理页收起最近流程导航以保留内容空间。明暗统一在“外观”选择，点缀固定鸢尾。
+
+健康检测以六色浅光谱区分候选、近期成功与受阻原因，详情默认折叠。连接检查只读目录或 ComfyUI 服务状态；可选轻量保活默认关闭，仅本次 Core 服务有效，服务重启不续开。媒体验证先准备指定模型的真实创作草稿，用户点击原生成按钮后才调用，可能计费。供应商可停用/恢复，删除须影响预览与确认，并保护当前工作区的未完成/可恢复依赖。详见[模型服务](PROVIDER_SETTINGS.md)。
+
+beta.1另有[网络出口与Doctor](NETWORK_WORKBENCH.md)：显式指定 `--network-config` 并加 `--allow-network-management` 后显示独立页面，管理节点、池及供应商出口；旧配置不自动迁移。模型服务/功能池旁显示配置摘要，原任务详情显示已记录路线。默认检查只读本地状态，点击检测才进行有界、无Provider Key的GET；系统TUN等未知状态不会猜测。
+
+ComfyUI 供应商支持 API 图/v0/v1 模板导入、开放参数及表单预览。创作时按明确模板显示 LoRA 双权重、种子和其他控件，LoRA/更多参数默认折叠，检查更新保留用户已展开的区块；结果详情显示原 Run 的参数快照。节点检查需要单独开启供应商管理，执行权限不会自动获得管理能力；见 [ComfyUI 使用](IMAGE_GENERATION.md#comfyui-入口)。
+
+## 能力总览
+
+beta.1另支持[有界媒体调度](MEDIA_SCHEDULING.md)：启动时显式指定 `--scheduler-config`，工作台可区分等待远端名额、模型冷却和本地 HTTP 队列；停止仍只结束本地等待。默认保持串行，不自动新增生成。
+
+侧栏“总览”或 Iris 标志进入六类能力卡片：图片、视频、语音、音乐、转写、视觉。也可在已有工作台地址后添加 `/#overview` 直接定位，登录与刷新沿用现有标签页会话；普通入口与 Run 深链接继续保留原创作行为。
+
+上方显示当前服务是否允许创作、图片/音频目录中的模型候选去重数，以及当前工作区的实际流程数。卡片分别呈现入口覆盖、已保存用途/功能池、当前候选和历史实测；标注用途与过去成功不等于现在可调用。实测记录只有在 owner 供应商管理已开启且读取成功时可见，其他会话标明“未提供记录”。读取失败显示未知，不当作零配置或成功；刷新不会读取远端模型目录或发起实测。
+
+图片、语音、转写卡片仅在当前根、执行权限与实际候选满足时启用对应创作按钮，点击只打开真实草稿，不提交任务。语音与转写需要v3/v4根；beta.1的新 v4 根另有[文生视频](VIDEO_FLOWS.md)入口并保留图片/音频。图生视频、S2V、音乐、视觉继续使用已有 CLI/DSH 入口。配置按钮只跳转已开启的模型服务页，不自动启用功能或改变授权。
+
+“更多 Core 工具”默认折叠，列出裁剪/差异、视频抽帧、HTML 截图与提示词优化的实际入口和依赖。各卡片的详细说明与最近实测时间也默认折叠，保留白色主体及浅鸢尾六色点缀。刷新总览不会覆盖供应商编辑草稿；明确保存供应商设置后，总览与当前候选随之更新。
+
+作品页仍按本工作区的 Run 及关联产物展示，不自动导入其他数据根或旧 DSH 资产。总览没有新增 API、权限、后台探测或数据格式。
+
+## 启动与连接
+
+需要 Node.js ≥22、项目现有依赖，以及已经初始化的专用 Flow 数据根。先确认图片流程是否已有记录；不要把 DSH 的普通 Core 根当作 Flow 根。
+
+```bash
+node bin/dsh-iris.js flow list --data-root /absolute/path/to/flow-root
+node bin/dsh-iris.js web serve --data-root /absolute/path/to/flow-root --port 4173
+```
+
+首次打开输出的 **`loginUrl` 设置访问口令**，之后直接打开普通地址。默认“记住此设备”30天，刷新、新标签页与正常重启继续使用；退出后输入同一口令即可。无需读取 Termux 私有文件或粘贴 Token，也没有反复获取短时登录链接的步骤。
+
+“退出登录”固定在页顶，滚动较长编辑页仍可操作；退出清除当前页面的连接配置导出、供应商草稿及健康详情，并沿用原会话撤销规则。退出不会删除作品、供应商配置或 MCP 授权，也不代表停止已经受理的媒体任务；服务级保活在服务关闭或显式关闭时停止。
+
+忘记地址或口令时，在本机用同一数据根操作，**无需重启运行中的服务**：
+
+```bash
+node bin/dsh-iris.js web login --data-root /absolute/path/to/flow-root
+node bin/dsh-iris.js web password reset --data-root /absolute/path/to/flow-root
+```
+
+重置会撤销全部工作台会话，返回新设置入口，保留作品、任务和 MCP 授权。初次设置入口没有10分钟倒计时，设置成功失效；尚未设置时重启会生成新入口。认证文件由 Iris 在私有目录管理，可显式 `--auth-store`。完整说明与旧 Token 模式见[工作台登录](WORKBENCH_LOGIN.md)。
+
+若没有 Flow 根，可先在新的专用位置执行 `flow init`；初始化是显式写操作，不由工作台自动进行。导入、创建、生成和选择的命令见 [图片流程](IMAGE_FLOW.md)。读取已有作品不需要 Provider 配置；若需显示配置中的模型候选，显式添加 `--provider-config /absolute/path/to/providers.json`。候选存在不代表实测成功；打开页面不探测模型，管理开启后可主动读取目录。
+
+默认随机端口，可用 `--port 4173` 指定。只监听 `127.0.0.1`，使用输出的完整地址，不能以 `localhost` 或代理 Host 替换。不会自动打开浏览器、启动 DSH 或重载其他进程。Ctrl+C 关闭。
+
+保持相同数据根、认证目录、固定端口和连接目录，可保留设备登录与已经导出的 MCP 配置。显式 Token 参数保留兼容，不是普通工作台的必填项。插件加载、业务/页面选择与完整命令见[稳定启动](PLUGIN_STARTUP.md)；不是后台守护或自动恢复租约。
+
+## 可用功能
+
+- 从历史查看真实持久 Run、原图与已保存结果；刷新读取最新本地记录。
+- 查看修改要求、状态和选择。详情及模型列表默认折叠，技术标识放在展开内容中。
+- 在权限开启时改图、保存原图/结果选择；服务确认后才显示已选状态和启用下载。下载保留原始图片字节与格式。
+- 切换历史、退出或重连。地址中的 Run 片段帮助重新定位，刷新后自动验证当前标签页保存的会话。
+- 对已有待核对动作，重新认证后按原创建 Key、Operation 或 Run 只读接回；“操作核对”默认折叠，可重新核对和查看流程。恢复表只含有限身份，详见 [请求恢复](WEB_RECOVERY.md)。
+- 作品页按全部、已选择或未选择进行服务器端筛选；计数和分页来自同一批真实记录，封面优先已选作品。只加载可见卡片预览，离开作品页释放预览 Blob。
+- v3 工作区增加语音合成和音频转写；音频直接播放/下载，转写按纯文本显示和下载。作品页按图片、语音、转写分类；音频卡片明确载入后试听，不自动加载整页音频。原图片根保持原入口。
+
+默认模式的媒体请求全部为 GET，创作与选择控件禁用并解释当前权限。刷新不查询外部任务、生成或修复数据；连接与供应商管理各有独立开关。
+
+## 开始一次真实改图
+
+完整创作需要新的专用 v1 根、明确的图片模型配置和独立选择开关：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/new-core
+node bin/dsh-iris.js execution init --data-root /absolute/new-core
+node bin/dsh-iris.js web serve --data-root /absolute/new-core \
+  --allow-execution --allow-selection --provider-config /absolute/providers.json
+```
+
+不要在已有 v0 创作根执行迁移；旧根仍可只读浏览或显式保存选择。Provider 配置格式见 [本地创建](LOCAL_CREATION.md)，配置候选不代表已实测。首次连接为空草稿，不预填演示作品或模型。
+
+选择/拖入不超过 20 MiB 的静态 PNG/JPEG/WebP，明确选择模型、填写要求，可展开填写模型支持的输出尺寸。点击“开始改图”后依次保存素材、建立 Run、执行一次改图；三个步骤各保留自己的 Key，双击合并，任一结果未确认或用户已离开时停止后续提交。Run 输入固定，修改要求需新建流程；“用已选作品新建”只建立本地草稿，不生成。
+
+切换流程时暂停执行、选择和复用，确认读到目标流程后再启用。读取失败时保持暂停，可重新读取或明确新建流程，不沿用上一流程的操作对象。
+
+已接收 Operation 期间最多低频 GET 40轮；隐藏标签页、离开创作或读取出错即暂停，可点击“刷新”明确接回。Operation 结束后再读取 Run；它结束不代表图片一定完成。异步任务需明确点击“查看原任务”，每次仅观察一次；受理未知保留原任务，不提供自动重提。保存失败的原结果和本地比较使用对应明确按钮接回。
+
+“停止等待”只停止原 Operation 的本地等待，不代表供应商取消、退款或未计费。选择采用当前 Run revision，冲突或回包丢失后读取当前选择，不自动覆盖。选择确认后可下载，实际保存位置和完成状态以浏览器下载记录为准。
+
+## 显式媒体权限
+
+`web serve` 与 `api serve` 使用相同的独立开关，不要求先开启连接管理：`--allow-local-writes` 开放零生成上传/创建；`--allow-execution` 同时开放创建与有限执行，需 v1/v2/v3 执行根及显式 Provider。`--allow-selection` 只开放 owner 图片持久选择，可直接用于已有 Flow 根，无需 Provider、创建请求区或执行器；音频单一结果无需选择。
+
+```bash
+node bin/dsh-iris.js web serve --data-root /absolute/path/to/flow-root \
+  --allow-selection
+```
+
+开关不会自动补齐其他权限。会话的 `readOnly`、`workbenchMediaReadOnly` 和 `operations` 反映当前调用方的媒体 API 权限，页面据此启用控件。仅选择模式无需 Provider；完整改图需执行，单独本地创建模式仍可通过 API 上传/建 Run。owner 选择权限不授予连接客户端。版本冲突与输入限制见 [持久选择](LOCAL_SELECTION.md)。
+
+## 显式开启连接中心
+
+需要已主动初始化的 v1/v2/v3 执行根；新根的准备见 [Core 服务](CORE_SERVICE.md)和[音频流程](AUDIO_FLOWS.md)。不要转换已有根。指定专用根外管理目录（父目录须存在）：
+
+```bash
+node bin/dsh-iris.js web serve --data-root /absolute/new-core \
+  --port 3182 \
+  --allow-connection-management --connection-store /absolute/new-connection-store \
+  --allow-mcp
+```
+
+目录为 0700、档案为 0600；首次只接受空目录，之后按 rootId 识别。管理目录与 Core 数据根相互独立，不改静态 grants 或客户端日常配置。目录自身只允许一个管理写者，复用现有租约。异常退出遗留租约时，先检查 `doctor --data-root /absolute/new-connection-store/ownership --json`，再按实际 stale PID 使用 `runtime recover`，不自动清锁。
+
+连接页面支持自由命名、创建、编辑、撤销、删除和 stdio/HTTP 配置导出。图片生成与编辑分别选择；v3 根另开放语音和转写；beta.1的新 v4 根再开放 video-generate，音乐、视觉仍未接入。工具细选默认折叠，操作权限与功能分开。默认只读服务只能分配 read；若要让 harness 导入、创建和执行，可在**同一个命令**显式增加 `--allow-execution --provider-config /absolute/providers.json`。执行服务会建立 runner 租约，接收/计费动作由用户或获授权客户端明确发起。连接管理不扩大媒体权限，owner 选择权限也不授予 harness。
+
+“新建连接”会进入编辑面板，提示、定位并聚焦名称，准备未保存草稿；填写后点击“创建连接”才保存记录，随后进入接入配置。默认改图草稿只包含所选功能对应的工具，不夹带生图工具。UUID、桥版本等位于“详情与管理”；切换分组或返回列表会清除凭据/Skill预览，不自动导出。
+
+创建不代表客户端已经加载。安装配置后，实际 MCP 客户端自报名称/版本会标记为“客户端声明”，桥版本独立记录；实例记录不保证进程持续在线。没有声明时显示未知，不扫盘推测安装状态。一个产品可按工作区创建多个连接。
+
+页面按“创建连接 → 生成配置 → 客户端启用”说明接入。stdio 由客户端按导出的 command/args 启动本机桥接进程；HTTP 使用已开启的 `/mcp` 地址及连接专属密钥，页面显示本服务的实际 HTTP 开关。两种方式都需要 Iris 服务继续运行。按所选客户端合并JSON或TOML，也可手动映射字段；只接受单条配置时选择entry。界面登录Token不用作MCP密钥。默认read只能浏览，要绘图需同时选择图片功能、create与execute，且服务已开启执行。
+
+“撤销连接”使旧配置失效但保留列表记录；“删除连接”经独立确认后使旧配置失效并移出列表，已撤销记录也能删除。两者都不删除作品、任务或已接收的操作，不取消远端生成，也不修改客户端配置。删除保留私有撤销档案和归档检查点，尚无界面恢复或永久清除入口；重放旧创建 Key 不会复活授权，详见 [存储与失败语义](CORE_CONNECTIONS.md#owner-连接中心)。
+
+stdio 配置引用本机私有客户端文件；HTTP 配置含连接密钥，只有点击生成配置时返回，复制/下载后应私下保管。隐藏配置、离开连接页或断开会清除预览；下载后也清空文本。普通列表不含凭据。编辑授权会立即影响后续调用；扩大名单后，stdio 客户端需重新启动以注册新增工具，缩小或撤销后旧进程不能绕过 Core 校验。已接收 Operation 保留，不等同于远端取消或停止计费。详见 [连接契约](CORE_CONNECTIONS.md)与 [MCP](MCP.md)。
+
+重复使用导出的配置时保持相同端口；服务改用其他端口后，需要重新导出并更新客户端。连接身份与撤销状态仍保留，旧配置不会自动寻找新端口。
+
+“接入模板”提供通用、Claude Code、Codex和Kimi Code两种传输的8个显式预设；不检测安装、不扫描或改写用户文件。Codex预览/复制/下载原生TOML，其余按所选JSON结构交付，HTTP未开启时对应预设禁用。保留手动入口与单条entry。来源及步骤见[MCP首次接入](MCP.md#首次接入与客户端预设)。
+
+展开“导入模板”也可下载示例并导入有界JSON：schemaVersion:0、标题、transport:stdio/http、format:mcpServers/entry/claude-json/codex-toml及可选HTTPS文档地址。导入保存到管理目录，相同内容不重复创建；旧文件与摘要不迁移。模板只选择传输与格式，不增加权限、不提供任意命令或代填凭据；内置预设不占自定义配额。
+
+展开“连接专属 Skill”，按**已保存且当前有效**的工具生成英文说明（附中文标题），可预览并下载交付 JSON。说明与配置分开，下载不表示安装；按页面命令显式指定 Skills 目录，再在客户端确认发现。权限变化后重新生成/安装，现有本地修改受到保护。见 [安装与边界](CORE_SKILLS.md#连接专属-mcp-skill03-alpha)。
+
+## 可选插件业务
+
+通过 `--plugin-config` 或公开 SDK 显式装配的[多图对照板](CONTACT_SHEET.md)已有实际制作页：选择现有作品与布局，经 Core 持久 Operation 排成新 PNG，刷新按原 UUID 接回；“业务记录”由 Core 内建，缺少插件仍可查记录和预览原图。客户端页默认不选择插件业务，用户勾选准确版本并允许执行后，导出的标准 MCP 配置才开放通用业务工具。此入口不改变媒体只读开关；启用选择和生命周期见[稳定启动](PLUGIN_STARTUP.md)。
+
+## 显式开启供应商设置
+
+在启动命令中增加 `--provider-config /absolute/existing-private-providers.json --allow-provider-management`。owner 可从“模型服务”或“管理模型”配置媒体连接、主动读取目录或手填模型、确认用途后一次保存。Key 不回显，冲突保留草稿。见 [C3 使用与管理契约](PROVIDER_SETTINGS.md)。此开关不隐含创建、执行、选择或 MCP 权限。
+
+## 会话与图片边界
+
+默认口令模式的首次设置票据放在 URL 片段中，页面读取后清除 URL 片段，并暂存在当前标签页的 sessionStorage 以支持刷新后继续设置；设置成功后清除且票据失效。登录/设置只接受严格同源的有限 JSON，返回独立浏览器 Bearer，不返回私有 owner 控制令牌。口令使用异步 scrypt 保存派生值，浏览器会话摘要与期限由根外私有认证存储持久保存，最多32个有效会话；正常重启保留，不自动挤掉其他登录。
+
+记住设备时，独立浏览器凭据保存在当前 origin 的 localStorage；未勾选则仅标签页 sessionStorage，期限分别30天/12小时。口令、owner 控制令牌和 MCP 密钥不进入浏览器存储。刷新和页面返回先只读验证；退出经服务确认后撤销会话、清除保存的登录和视图，释放图片 Blob。401 清除旧浏览器登录，业务 Run 身份保持；登录不生成媒体，存储不可用明确提示。旧 Token 模式继续使用原标签页会话与一次性链接，详见[登录边界](WORKBENCH_LOGIN.md#凭据边界)。
+
+未确认动作的身份单独保存在有界 sessionStorage，绑定 origin 和稳定 rootId，不含 Token、Prompt 或文件。换根只丢弃旧客户端标识，存储不可用时提示内存模式；重连恢复仅 GET。未知创建核对成功后可打开原 Run，不自动首次执行；未完成请求需明确提供原输入后按原 Key 接回。
+
+静态资源使用默认固定白名单、明确选中插件的固定 JS/CSS，或替代 Panel 清单，登录页不含私有数据。[组合插件挂载](PLUGINS.md#web-贡献和生命周期)共享当前主题、登录与 API；页面进入导航，设置默认折叠，作品区可选择匹配实际 MIME 的扩展预览，原生查看保持可用。只有可信同源模块适用，样式隔离不等于权限沙箱。
+
+允许从其他页面顶层导航到公开首页；外站 fetch、iframe、资源与业务 API 不获得此例外。登录流程以外的 API、图片和下载仍要求 Bearer，保留 Host/Origin 与无 CORS 的约束。不提供任意目录、Provider 原配置或私有路径。供应商编辑投影仅在管理开启后对 owner 提供，含端点、不含 Key。图片只支持 PNG、JPEG、WebP，上限沿用只读 API 的 64 MiB。
+
+下载成功只说明请求已交给浏览器，实际位置与完成状态以浏览器下载记录为准。像素差异描述变化程度，不是质量评分。
+
+## 验证与下一阶段
+
+源码验证使用隔离根与受控 Provider，不读取日常配置或进行付费生成：
+
+```bash
+node tests/local-web.mjs
+node tests/workbench-auth.mjs
+node tests/workbench-password-api.mjs
+node tests/workbench-password-cli.mjs
+node tests/panel-extension.mjs
+node tests/plugin-panel.mjs
+node tests/provider-settings.mjs
+node tests/local-selection-api.mjs
+node tests/local-creation-lookup.mjs
+node tests/web-recovery.mjs
+node tests/web-media-api.mjs
+node tests/local-gallery-api.mjs
+node tests/core-connection-store.mjs
+node tests/connection-management.mjs
+node tests/connection-delivery.mjs
+node scripts/verify-local-web-browser.mjs --browser-executable /absolute/path/to/chromium --output /absolute/path/to/new-evidence-directory
+```
+
+需要已有 Chromium，不下载或安装；加 `--connection-management` 验证真实管理交互，`--allow-selection` 开启选择模式但不自行点击写入。`--recovery` 用独立测试动作验证恢复；`--creation` 在隔离根经生产页面实际点击创作、选择、下载、异步观察、停止、版本冲突和回包丢失，仅 Provider 为受控夹具。`--mode-closure` 单独验证未确认执行在权限降级与恢复后保留原身份、只读核对及明确接回，不与其他场景开关组合。仅在受控测试确有需要时追加 `--no-sandbox`。桌面模拟手机宽度、200% 等效布局宽度不等于 Android 真机或浏览器原生缩放验收。
+
+`--panel-c3` 单独验证外观持久化、配置/冲突/回包丢失、窄屏及配置后受控真实改图，不与其他场景开关组合，不调用付费媒体。
+
+`--provider-workbench` 单独验证三类模型服务入口、独立模型池保存、连接检查/保活、验证草稿与一次真实 Core 夹具改图，以及供应商停用/恢复/删除、两类编辑取消、长页退出和390像素/桌面/明暗布局。配置与服务均隔离，无真实付费调用；API 与生命周期边界另运行 `node tests/provider-workbench-api.mjs` 和 `node tests/provider-monitor.mjs`。
+
+`--plugin-panel` 单独装配独立测试插件，验证页面、默认折叠的设置表单、实际作品字节预览，以及共享会话/主题、只读权限、切页/退出/迟到清理和按阶段定位错误。使用隔离数据与配置，不加载个人背景或调用真实媒体服务；桌面 Chromium 的窄屏模拟不代替手机实机验收。安装插件本身不启用这些模块，实际接入见 [插件装配](PLUGINS.md#web-贡献和生命周期)。
+
+`--image-generation` 单独验证新 v2 根的文生图、恢复与选择下载、能力选择及 ComfyUI 导入/HTTP 队列链路；ComfyUI 为受控响应，不能替代实际 GPU 出图。
+
+`--comfyui` 单独验证 Core v1 模板导入/命名/预览、只读检查与失效、LoRA 候选及参数快照、原任务观察和历史参数查看，包含窄屏/主题/减少动画。使用同一验证脚本的 `--browser-executable`、`--output` 及适用的 `--no-sandbox` 参数；此项同样使用受控服务，不执行真实 GPU 推理。
+
+`--panel-feedback` 单独验证默认新建连接的保存/导出、MCP 接入说明、手机定位、删除确认/取消/撤销后删除、供应商 ComfyUI 切换动画与自定义 API 草稿恢复，以及标签页刷新登录、退出、重启失效、坏缓存和禁用存储。使用隔离配置，不写日常预览数据；刷新与登录恢复只读，不提交媒体。
+
+`--password-login` 单独验证默认口令登录：首次设置、重复口令校验、刷新/新页/正常重启、退出撤销/原口令再入、禁用存储/坏缓存、重置及设置/退出回包丢失；覆盖手机宽度/桌面/深色，不提交媒体或读取个人背景。
+
+`--login` 验证旧 Token 模式：从其他页面点击一次性链接、片段清除、同标签页刷新、用过的链接提示、备用 Token、同页新链接、重启失效与新链接接回、取消迟到兑换、禁用存储和坏片段；不提交媒体或管理写入。与其他场景开关分开使用。
+
+`--video` 单独验证beta.1的新 v4 文生视频：真实 MP4 解码/播放和原字节下载、原任务重启接回、丢失创建回包、本地停止、只读、窄屏和暗色。此验证仅使用受控 Provider，见[视频边界](VIDEO_FLOWS.md)。
+
+`--audio` 单独验证新 v3 根上的 TTS、音频导入/转写、原 Task 明确观察、音频实际解码/播放、WAV与UTF-8下载、刷新零重提、创建回包丢失、作品分类、只读以及桌面/窄屏/主题。Provider 使用受控响应，不等同于真实付费服务验收；边界与对应定向测试见[音频流程](AUDIO_FLOWS.md)。
+
+`--overview` 单独验证六类能力、旧根/音频根与只读边界、四种草稿跳转、历史实测、未知/失败状态、刷新保留供应商草稿、明确保存后的同步和手机/明暗布局。使用隔离配置与受控执行端口，检查浏览/刷新与草稿跳转不写 Core、不调用供应商；不与其他场景开关组合。
+
+源码已把 [有限执行](CORE_SERVICE.md)、[持久选择](LOCAL_SELECTION.md)、[原身份恢复](WEB_RECOVERY.md)、文生图及供应商设置接到真实页面，并补充本机受控验证。标准平台按对应提交CI核销，真实设备与账号按各自证据验收；其他媒体和最终演示素材按 [路线图](ROADMAP.md)推进。本页对应beta.1；受控浏览器检查与真实供应商验收分开记录。

package/docs/MCP.md

@@ -0,0 +1,212 @@
+# 通用 MCP 接入与能力选择（0.3 beta）
+
+新用户先看[从零启动与页面接入](CORE_QUICKSTART.md#connect-an-agent--连接客户端)；交给安装/使用 Agent 的可复制说明见 [Agent Core 指导](AGENT_CORE_QUICKSTART.md)。本页详述传输、模板与授权契约。
+
+同一套 Iris MCP 工具可通过 stdio 或 Streamable HTTP 接入支持对应传输和协议的客户端。无需为每个产品编写 Adapter，客户端名称也不用于授予能力。**通用 MCP 入口从0.3.0-alpha.1提供，稳定 npm 0.2.7 不包含**；安装准确beta版本或使用当前源码；最小面见[beta约定](BETA_SCOPE.md)。
+
+业务数据、Operation、执行队列和 Provider 均归同一个 [Core 服务](CORE_SERVICE.md)。MCP 负责协议和工具交付，使用官方 SDK 2.3.1；不启动第二个业务写者，也不把调用转成 Shell 命令。当前媒体范围为固定 `image-edit/v0`、[文生图 `image-generate/v0`](IMAGE_GENERATION.md)，以及新 v3 根上的 [speech/v0 和 transcribe/v0](AUDIO_FLOWS.md)。文生图需要 v2/v3 根，音频需要显式 `execution init --audio` 新根，原根不迁移。**beta.1**另支持新 v4 根上的[固定文生视频](VIDEO_FLOWS.md)，通过 `execution init --video` 显式创建；v4 保留图片/音频能力，已发布 alpha.1 不支持该开关。
+
+工具输入、功能归属、权限和指导来自同一 [Core 能力目录](PLUGINS.md#core-能力目录与授权)。MCP 导出服务、功能选择、scope、已保存 tools 的交集；Skill 从同源声明解释工具。安装/发现插件不授权；页面/渲染器也不默认挂载。显式开启的插件业务现已接入持久 Operation，经用户保存的准确 `pluginOperations` 依赖选择调用，旧连接不扩权。
+
+选择带图片输入的业务后，目录与图片工具可读取同一数据根内共享的 PNG/JPEG/WebP 来源（≤8 MiB），包括其他业务的图片；其他业务的调用和历史仍不开放。没有图片输入的业务不隐含图库权限，实际处理器只读取本次绑定的来源；完整边界见[连接授权](CORE_CONNECTIONS.md#身份与授权)。
+
+## 可选真实插件业务
+
+先按[稳定启动](PLUGIN_STARTUP.md)启动 Core，并在 `--plugin-config` 明确装载与启用业务。普通工作台使用[访问口令](WORKBENCH_LOGIN.md)，浏览器登录与 MCP 连接密钥独立。使用固定端口与原连接目录可复用已导出的 MCP 配置；旧 Token 模式的 owner 会话轮换也不轮换连接密钥。不要将 `mcp serve` 当作 Core 启动命令。
+
+[多图对照板](CONTACT_SHEET.md)通过公开插件 SDK、现有 Sharp 和 Core 作品存储处理真实图片。服务装配者选择业务，用户在 Web 连接页选择准确依赖并允许执行，客户端再通过通用 `iris_core_plugin_catalog` 获取业务输入 Schema、可用性和来源图片，调用 `iris_core_plugin_call`。执行工具固定为 `{key,operationId,dependency,input}`；不为每个插件复制工具名单，也不提供 shell 或任意 Core 命令入口。
+
+回执、原 UUID 接回、停止和图片继续使用 `iris_core_operation/lookup/stop/image`。插件业务 succeeded 表示处理器返回且 Core 命令完成；媒体流程的 succeeded 仍仅描述一次有限继续。缺失/不同版本插件阻止新执行，原记录和作品不依赖插件实现；重启保留 interrupted，不自动重做。缩权让旧握手失效，下一次 Core 命令继续核对持久授权；已入库作品不回滚。
+
+仅选此业务并允许 read/execute/stop 时有8个工具，权限缩减后进一步过滤。未选择业务的连接不获新增工具；media只读服务也不会因插件 execute 而开放 continue。官方客户端已验证 stdio/HTTP、2025-11-25/2026-07-28协议、原 UUID/图片恢复及负向授权边界；这不代表所有 harness 已完成附件展示实测。
+
+文生图创建可带 `workflowParameters`，仅使用所选 ComfyUI 模板明确开放的参数 ID 和标量值。先通过 `iris_core_models` 读取描述；参数随 Run 保存并纳入原请求 Key，不能传任意图补丁。节点/模型的只读检查属于 owner 配置接口，未新增 MCP 管理工具或扩张已有连接权限；Core 工作台已接通导入预览、参数表单和结果参数查看，DSH 的独立工作台入口见 [DSH ComfyUI](IMAGE_GENERATION.md#dsh-工作台入口03-alpha)。
+
+## 首次接入与客户端预设
+
+### 工作台连续接入（当前源码）
+
+以下接入核对页从 **0.3.0-beta.1** 提供；原有模板、CLI与授权契约保持。
+
+1. 在“客户端 → 新建连接 → 选择与授权”选择实际媒体功能或准确插件业务，核对摘要后保存。只读授权可以浏览；不要为通过检查而自动扩大权限。
+2. 在“获取配置”确认 **Agent 是否与 Core 同机**，再选择模板或通用格式。这里的机器指运行 Agent 的主机，不是打开网页的浏览器设备。当前 stdio 路径和 HTTP 回环地址不能直接交给另一台机器；未保存的功能/权限修改会阻止导出，已有客户端仍按原授权访问。
+3. 生成并合并配置到客户端，保留已有条目，再打开“核对接入”。“配置已生成”仅表示本次登录内存中对当前修订/格式的生成记录；复制或浏览器下载不证明客户端已经导入。刷新后没有本页记录，也不说明用户从未导出。
+4. 点击“检查 Iris 端与接入记录”，只读取当前 owner 会话、实际目录和保存授权，展示配置受限原因及 Core 当前允许的工具。它不建立桥接实例、不测试 stdio/HTTP 客户端传输，也不验证每项媒体功能、模型或 GPU。HTTP 未开、异机方案、准确插件依赖和零工具等问题分别解释，不自动授权。
+
+“Iris 端配置检查通过”与“收到客户端握手与声明”分开呈现。客户端名称/版本是可选、自报元数据；只有桥接握手、CLI 自检或配置下载不会被标为 Agent 已接入。未收到声明不等于业务调用失败；可在客户端明确调用一个已授权只读工具后重新核对。协商工具按实际 scopes 过滤，明细默认折叠；历史/断开不伪装持续在线，声明也不证明客户端发现或展示了全部工具。
+
+检查和导出的本页状态不会新增持久格式。切页取消只读检查，退出清除配置预览、导出/检查记录和客户端声明展示；收回权限或撤销后仍由 Core 在真实调用时执行原有门禁。
+
+### CLI 检查与预设（alpha.1 已有）
+
+Core由用户明确启动并保持运行；stdio桥由客户端启动和关闭，HTTP客户端连接已开启的 `/mcp`。桥退出只结束自己的连接，不停止Core或已受理的媒体操作。连接页记录最近使用与握手事实，不把它称为客户端持续在线。
+
+客户端名称/版本上报属于可选元数据，失败或延迟不阻塞已授权工具，也不替换业务回执。握手、持久授权和每次 Core 命令的权限核对继续生效；元数据上报不授予权限。
+
+已有明确的 client.json 后，可先检查再导出：
+
+```bash
+node bin/dsh-iris.js mcp check --connection-file /absolute/pair/client.json
+node bin/dsh-iris.js mcp presets
+node bin/dsh-iris.js mcp config --connection-file /absolute/pair/client.json \
+  --preset codex-stdio --output /absolute/new-iris-mcp.toml
+```
+
+`check`默认只请求read，检查私有配置、Core回环传输、原身份握手和实际工具选择，随后断开临时实例；返回JSON，失败退出码为1。可用 `--scopes/--capabilities/--tools` 明确检查实际要用的子集，不修改原授权。它不调用供应商，也不证明模型、客户端加载或 `/mcp` 协议链路已实测；后者仍需在客户端确认。Core未运行时返回transport阶段与建议，不自动创建根或启动另一份服务。
+
+内置8个预设由用户选择，不检测安装、不读取或合并日常客户端配置：
+
+| 前缀 | 格式与使用方式 | 官方依据 |
+|---|---|---|
+| generic | 通用mcpServers JSON，也可手动选择entry | [MCP本地接入](https://modelcontextprotocol.io/docs/develop/connect-local-servers) |
+| claude | 带type=stdio/http的mcpServers JSON，合并到明确选择的.mcp.json | [Claude Code MCP](https://code.claude.com/docs/en/mcp) |
+| codex | 原生 `[mcp_servers.iris]` TOML，command/args或url/http_headers | [OpenAI官方配置](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) |
+| kimi | command/args或url/headers的mcpServers JSON，合并到明确选择的mcp.json | [Kimi Code MCP](https://moonshotai.github.io/kimi-code/en/customization/mcp) |
+
+每个前缀分别使用 `-stdio`、`-http`，如claude-http。预设只选择传输、格式和说明，不增加媒体功能、scope或工具；不能与手动 `--transport/--format` 混用。其他客户端继续使用通用入口或数据模板。合并时保留已有文件与其他条目，不把本次片段直接覆盖成完整日常配置。
+
+手动格式支持mcpServers、entry、claude-json、codex-toml。TOML导出为实际文本及.toml文件；JSON继续为对象及.json文件。HTTP预设仍需服务显式开启HTTP MCP；CLI含密钥导出仍只写新的原连接私有目录文件，拒绝stdout与覆盖。工作台复制/下载是用户明确操作，含密钥内容仅交给获授权客户端。
+
+## 创建明确的连接
+
+也可使用 [Core 连接中心](LOCAL_WEB.md#显式开启连接中心)创建、编辑和撤销，再从页面导出配置。此模式显式指定私有管理目录；名称自由填写，不依赖内置品牌名单。下面保留原静态文件配置方式，两者可共存。
+
+先初始化新的专用根，保留现有 DSH/旧请求根：
+
+```bash
+node bin/dsh-iris.js flow init --data-root /absolute/new-core
+node bin/dsh-iris.js execution init --data-root /absolute/new-core
+node bin/dsh-iris.js connection create --data-root /absolute/new-core \
+  --directory /absolute/new-mcp-pair --origin http://127.0.0.1:3182 \
+  --label my-client --scopes read,create,execute,stop --capabilities image-edit
+```
+
+MCP 默认 `generic`，不必填写 Kimi、Claude 或其他产品名。`--label` 是用户可辨认的连接名称；原 `--harness kimi` 仍可用，`--harness dsh` 留给 DSH 原生服务桥。连接与权限见 [连接契约](CORE_CONNECTIONS.md)。
+
+```bash
+node bin/dsh-iris.js api serve --data-root /absolute/new-core \
+  --provider-config /absolute/providers.json --port 3182 \
+  --token-file /absolute/new-owner-token.txt --allow-execution \
+  --connections-file /absolute/new-mcp-pair/server-grants.json --allow-mcp
+```
+
+`--allow-mcp` 才开放标准 `/mcp`，与现有 Core 共用端口。默认关闭；不传 `--allow-execution` 时仍按服务已开启的权限提供有限工具。创建连接、导出配置、初始化和工具发现不调用模型。
+
+## 选择能力和工具
+
+功能分组与操作权限分开。当前可选媒体分组为 `image-edit`、`image-generate`、`tts`、`transcribe`；beta.1另有 `video-generate`，根版本进一步限制实际可用分组；查看工具总目录：
+
+```bash
+node bin/dsh-iris.js mcp capabilities
+```
+
+- `--capabilities image-edit`：图片导入、流程、模型查询、单次继续、原操作查询、本地停止和原图读取。
+- `--capabilities image-generate`：独立文生图创建、流程/模型查询、单次继续、原操作查询、本地停止和结果读取；可用 `image-edit,image-generate` 同时选择。原默认仍仅 image-edit。
+- `--capabilities tts`：实际语音候选、文字/可选音色创建、原音频内容及共享 Run/Operation 工具；仅在 v3 根（beta.1也支持 v4）开启。
+- `--capabilities transcribe`：实际转写候选、原音频导入/来源ID创建、音频与文字读取及共享 Run/Operation 工具；仅在 v3 根（beta.1也支持 v4）开启。可用 `tts,transcribe` 同时选择。
+- `--capabilities video-generate`（beta.1）：新 v4 根的实际文生视频候选、保存意图、原视频资源引用及共享 Run/Operation 工具。视频返回 `resource_link`，用标准 `resources/read` 读取 MP4/WebM（≤32 MiB），每次读取检查当前授权；客户端播放支持需另行确认。
+- `--capabilities none`：关闭媒体流程工具，保留两项连接管理工具。
+- `--tools iris_core_models,iris_core_image`：在分组范围内进一步选择具体工具；`--tools none` 注册零工具。明确工具名单不会暗中补齐连接工具。
+- `--scopes read`：只读；`create` 允许上传/建 Run，`execute` 允许明确继续，`stop` 允许本地停止。必须包含 read；首次继续可能产生模型费用。
+
+这些选项可用于 `connection create`。服务端按连接授权检查实际 API 路由，猜工具名或绕过 MCP 也不能调用未选择的功能。stdio 客户端还可进一步缩小本次 `mcp serve` 的范围；HTTP 以该连接在服务端的明确授权为准，需要不同范围时创建各自的连接。
+
+新连接将能力和具体工具列表写入私有授权。后续版本增加新工具不会扩大已有列表。旧文件缺少这两个字段时按原有图片流程和固定 12 工具解释，读取不改文件；未知分组、未知工具和未接入的媒体功能明确拒绝。
+
+## stdio：填写启动命令
+
+导出当前 Node 与实际包入口的绝对路径，复制到接受 `mcpServers` 格式的客户端：
+
+```bash
+node bin/dsh-iris.js mcp config \
+  --connection-file /absolute/new-mcp-pair/client.json \
+  --scopes read,create,execute,stop --format mcpServers
+```
+
+也可 `--format entry` 仅输出 command/args。配置不包含认证值，命令从指定私有文件读取它。不同客户端的配置文件格式可能不同；按该客户端要求填写同一组 command/args。导出器不修改或扫描客户端配置。
+
+其启动命令为：
+
+```bash
+node /absolute/iris/bin/dsh-iris.js mcp serve \
+  --connection-file /absolute/new-mcp-pair/client.json \
+  --scopes read,create,execute,stop
+```
+
+省略 scopes 时请求只读。stdout 只传 MCP 消息；正常 EOF 关闭桥。桥退出或请求取消不撤销 Core 已接收的 Operation，重连用原 Key 查询。
+
+## HTTP：填写 URL 和认证
+
+服务启动后 MCP 地址为 `http://127.0.0.1:3182/mcp`，使用标准 `Authorization: Bearer …`；客户端无需实现 Iris 内部身份头或业务握手。每个连接使用自己的凭据和能力范围。
+
+导出包含认证的配置须明确写入原连接私有目录的新文件：
+
+```bash
+node bin/dsh-iris.js mcp config \
+  --connection-file /absolute/new-mcp-pair/client.json --transport http \
+  --output /absolute/new-mcp-pair/mcp-http.json
+```
+
+stdout 只返回输出位置等元数据；文件以 0600 排他创建，不覆盖已有内容。按客户端自己的格式复制 URL/headers；此文件包含凭据，应与 client.json 一样私有保管。HTTP 的 scopes/分组/工具在授权文件中选择，导出时不通过客户端自报字段扩大或改变它们。
+
+HTTP 使用官方 `createMcpHandler`，提供 2026-07-28 请求元数据模式及 2025-11-25 的无状态兼容路径；旧协议 GET/DELETE 的可选会话操作返回 405。Host/Origin 和 Bearer 在 SDK 前校验，仅回环监听。静态文件仍仅启动时读取；连接中心的显式 owner 操作可即时变更授权。该入口没有公网发布、OAuth 登录或自动端口发现。
+
+**beta.1的负载预算**：同一 Core 的所有 HTTP MCP 连接共享4条活动消息额度，从读取正文前占用，直到响应排空、失败或断开后释放。兼容路径的批量请求按消息条数占用，单批最多4条，超过返回400及 `IRIS_MCP_HTTP_BATCH_TOO_LARGE`；剩余额度不足返回429、`Retry-After: 1` 及 `IRIS_MCP_HTTP_BUSY`，不会在入口排队。正文仍限9 MiB，原有图片/音频/视频大小限制保持；这是活动请求预算，不是进程内存配额，也不限制远端持久任务数量。
+
+入口有界读取正文，超限后丢弃剩余上传；解析结果通过官方 SDK 的 `parsedBody` 接口交付，协议校验仍由 SDK 完成。慢上传或未排空的媒体响应占用额度；连接取消只结束本地等待，已受理 Operation 继续按原 Key 查询。客户端收到429后可稍后显式重试；写操作继续保留原 Key，不自动换 Key 或重新生成。此额度仅用于 HTTP MCP，stdio、工作台控制接口和[媒体调度](MEDIA_SCHEDULING.md)分别管理各自资源。
+
+当前每项 HTTP 授权在 Core 中对应一个逻辑桥实例。共享同一凭据的多个程序不被猜测为不同产品或真实在线进程；需要分别查看/授权时使用独立连接。该数据空间仍是同一用户共享作品，不是连接之间的数据租户隔离。
+
+实际客户端的标准名称/版本以“客户端声明”显示，桥版本另外记录，不作为认证依据。新增工具权限后，stdio 需要重新启动加载工具表；收回权限或撤销后，旧进程也无法绕过 Core。连接中心仅在明确导出时返回 HTTP 密钥；CLI 的 HTTP 导出继续要求新建私有文件，不打印认证值。
+
+标准传输依据 [MCP Streamable HTTP](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http)；SDK 装配见 [HTTP serving](https://ts.sdk.modelcontextprotocol.io/v2/serving/http.html)。
+
+## 功能覆盖
+
+以下 Core 列表示已有代码入口，具体运行仍需有效配置、模型或相应本地组件；不表示所有部署/账号均已实测。
+
+| 功能 | Core/CLI | 当前 MCP |
+|---|---|---|
+| 静态图片导入、原图读取 | 已有 | image-edit 分组支持 |
+| 固定图片编辑 Flow、Run/原 Task 查询、比较图引用 | 已有 | image-edit 分组支持 |
+| 单次继续、原 Key 接回、本地停止 | 已有 | 图片/音频分组支持；源码另支持视频，按原 Run 能力检查 |
+| 明确选择作品、导出到本机路径 | 已有 | 尚未接入，继续使用 CLI |
+| 独立文生图 | 已有 | image-generate 分组支持；新 v2/v3 执行根，明确模型与单张输出 |
+| TTS、原音频读取 | 已有 | tts 分组，新 v3 根，标准 audio 内容块，实际播放器取决于客户端 |
+| 音频导入、转写与文字读取 | 已有 | transcribe 分组，新 v3 根，持久来源与原任务恢复 |
+| 文生视频 | 已有 | beta.1的 video-generate 分组，新 v4 根，标准资源引用与读取；已发布 alpha.1 未接入 |
+| 图生视频/S2V、Music | 已有 | 尚未接入 |
+| 视觉、OCR、定位、摘要 | 已有 | 尚未接入 |
+| 裁剪、像素差异、抽帧、HTML 截图 | 已有 | 尚未接入 |
+| 全媒体任务/作品管理及可恢复维护 | 已有 | 仅有固定流程所需的有限读取，其余尚未接入 |
+
+增加媒体能力时，先接入已有 Core 的受理、原身份恢复和产物交付，再作为新分组让用户明确选择，不添加 `all` 自动扩展已有连接。
+
+## 错误定位
+
+`mcp check` 的error、stdio启动失败的stderr和工具错误包含安全错误码、阶段与处理建议；Core已返回关联ID时保留requestId。工具错误的 `structuredContent.error` 另保留已校验的原key/runId/operationId，不复制私有异常、Provider正文、凭据或任意路径。
+
+| 阶段 | 处理方式 |
+|---|---|
+| configuration | 核对明确选择的私有client.json；server-grants.json和owner Token不是客户端文件 |
+| transport | 核对已启动Core的回环地址与端口；超时后保留原Key，先查询原操作 |
+| handshake / authorization | 核对原根、连接身份、已保存选择与服务开关，再由所有者明确导出或调整 |
+| input / tool / response | 按当前Schema与原Run/Operation检查；Run版本变化先读取当前修订，不自动重提 |
+
+stdio stdout保持MCP协议专用。EOF、明确关闭或启动取消会关闭桥与本地网络等待；关闭与初始化竞态不会重新打开客户端。远端实例断开有confirmed/unconfirmed结果，不把本地停止当作供应商取消或退款。
+
+## 验证范围
+
+新增接入预设已进行独立TOML解析、八类配置的真实stdio/HTTP协议工具交付、CLI检查及隔离浏览器复制/下载验证；未实际启动Claude Code、Codex、Kimi Code原生会话，不把格式验证称为所有客户端版本已验收。
+
+早期图片切片验证 stdio/HTTP × 2025-11-25/2026-07-28，每个组合实际调用全部 12 个工具；另以两份独立已安装的官方 Client SDK 2.0.0/2.2.0 重跑四个组合。覆盖真实 Core 持久记录、原图字节、原 Key 跨进程/传输接回、能力/权限交叉、断开、本地停止和重启。Provider 响应为离线夹具，没有付费模型调用。
+
+另有文生图 stdio/HTTP 定向验收，覆盖新增创建工具、原 Key 和共享工具的功能授权；原 image-edit 仍为 12 工具，只选文生图为 11 工具，两者完整选择为 13 工具。新组不自动扩张旧文件或授权。
+
+音频另以受控 Provider 验证 HTTP 2025/2026、真实 stdio 2026 进程、标准 audio 内容块、UTF-8转写、分组/媒体入口隔离、连接 Skill、原Key和重启恢复。没有调用真实付费服务，不代表所有 harness 都支持音频播放；输入与大小边界见[音频流程](AUDIO_FLOWS.md)。
+
+这些结果不代表每个品牌客户端或 Agent 的自主使用都已验收。DSH 的可选原生桥与三项 Skills 保持；Skill 发现/安装仍按 [Core Skills](CORE_SKILLS.md)单独处理。真实 Web 按显式开关提供连接管理与媒体操作，默认只读。
+
+连接中心还支持[纯数据模板和连接专属 Skill](LOCAL_WEB.md#显式开启连接中心)：模板只选择现有传输与 JSON 格式，Skill 按当前有效工具生成，下载后用 `skills install --bundle` 显式安装。配置、工具权限和使用说明各自独立；Skill 不提供身份凭据，不自动注册 MCP 或扩展连接权限。这些入口均为0.3 beta能力。
+
+文生图连接的 Skill 对 ComfyUI 先确认缺少的工作流、LoRA 与参数要求，再使用实际目录中的 `modelRef` 和 `comfyWorkflow.parameters`。目录工具、执行工具或改图工具未开放时，说明会相应限定调用和搭配，不提供越权的替代路径。当前可将 ComfyUI 输出作为同根作品交给支持改图的 API，反向图片输入尚未接入；详见 [ComfyUI Skill 参考](../skills/iris-core/references/comfyui.md)。

package/docs/MEDIA_SCHEDULING.md

@@ -0,0 +1,72 @@
+# 有界媒体调度（0.3.0-beta.1）
+
+本页功能从 `0.3.0-beta.1` 提供，旧alpha.1不包含。默认仍使用串行写入队列；在 `api serve` 或 `web serve` 的现有启动命令增加 `--scheduler-config /absolute/private/scheduling.json`，才启用本片调度。它不启动第二个写者，不扫描配置，不迁移已有数据，不修改全局代理或系统路由。
+
+## 启动策略
+
+新建仅当前用户可读写的普通 JSON 文件（POSIX 建议 `0600`），例如：
+
+```json
+{
+  "schemaVersion": 1,
+  "httpConcurrency": 4,
+  "requestsPerSecond": 2,
+  "remoteLimit": 8,
+  "queueLimit": 32,
+  "queueTimeoutMs": 30000,
+  "providers": [
+    {
+      "providerId": "my-provider",
+      "httpConcurrency": 2,
+      "remoteLimit": 4,
+      "models": [
+        { "modelId": "my-image-model", "requestsPerSecond": 1, "remoteLimit": 2 }
+      ]
+    }
+  ]
+}
+```
+
+全局字段除了 `schemaVersion` 均可省略，默认值如上；供应商、模型层只限制填写的项目，与上层同时生效。名称必须与当前 Provider ID、原始模型 ID 准确匹配，不按显示名或客户端品牌匹配。没有填写供应商条目时，全局限制仍生效。配置在启动时读取一次，当前没有编辑 UI 或热更新。
+
+`httpConcurrency` 为 1–4；`requestsPerSecond`、`remoteLimit` 为 1–1000；`queueLimit` 为 8–128；`queueTimeoutMs` 为 1–300000 毫秒。全局 HTTP 并发首片最多 4，这不是厂商容量声明。未知字段、其他版本、重复身份、缺失文件或过宽文件权限会明确拒绝，不静默退回无调度模式。
+
+## 三种限制的区别
+
+| 限制 | 统计边界 | 释放条件 |
+| --- | --- | --- |
+| HTTP 在途 | Core 实际交给传输 dispatcher 的请求，包含提交、查询、上传、下载和重定向的每一跳 | 正文传输结束、取消或传输失败；收到响应头尚不释放 |
+| RPS | 实际调用 dispatcher 的滚动一秒窗口，全局与准确供应商/模型同时检查 | 时间窗口经过；不预订未来时间后同时突发派发 |
+| 远端未结束数 | 同根 Task 已受理、受理未知或已有未收敛提交意图，且未确认成功/失败/取消 | 原 Task 确认远端终结；本地停止、关闭页面或 Operation 结束不释放 |
+
+RPS 是应用派发口的限制，不证明网络或上游服务收到报文的精确时刻。出口连接预检、TCP/CONNECT 连接和其他进程的流量不计入业务 HTTP 次数。已有路线记录证明 Core 在请求前保存了选择，可能在排队或取消前已经写入，因此不能把 Task 的路线 `requestCount` 当成调度器的实际派发计数。
+
+远端额度只拦截新的提交；原任务查询、取消和下载仍可执行。调度前从严格校验的现有 Task 事实计算额度，重启不会忘记未知任务。历史读取目前仍有线性成本，没有宣称支持无限历史规模。
+
+beta.1中，损坏Task导致远端数量无法确定时，owner session仍可读取，调度摘要返回`remoteOutstanding:null`及`remoteError`错误码，不把未知数量显示为0。新提交继续严格检查原记录，不通过跳过坏Task放宽名额；相关等待者收到同一可定位错误，纯观测失败不升级为无关写者释放失败。修复原记录后可重新读取，不自动删除、隔离或改写Task。
+
+## 排队、取消与恢复
+
+Core 在网络等待期间让出短写入执行权，恢复后串行保存结果。每项工作有独立取消信号，同 Task 生命周期、同 Run 和创建 Key 保持互斥。未知插件业务写回调继续独占，不因增加媒体并发就自动获得并行执行保证。
+
+已知模型短时冷却时，新生成在创建提交意图前等候；额度/预算耗尽仍需明确实测解除。HTTP `429` 的 `Retry-After` 约束后续请求，不自动重试失败的 POST。未派发的 HTTP 取消/排队超时保持明确未受理；一旦派发后结果不明，仍按原受理未知边界处理，不切换出口或模型重放。
+
+等待有明确期限和有界内存队列；队列满或等待超时返回可定位错误。Flow 已固定的 Task 身份可能已有零 Attempt 的占位，但不会为了等名额创建大量失败提交。当前最多保留 8 个未结束的持久 Operation；启用调度时最多 7 个新提交，保留一个位置供已有任务的继续、查询和交付。停止本地 Operation 不需要另占此位置。
+
+未开始的 HTTP/写入队列直接返回 `IRIS_SCHEDULER_QUEUE_FULL` 或 `IRIS_SCHEDULER_QUEUE_TIMEOUT`。已接收的 Operation 保留既有 `execution_failed` 持久类别，具体调度错误码在 Core 进程日志中关联原 Operation ID；没有为此迁移 Operation 格式。临时等待阶段不会跨重启保留。
+
+本地写入 admission 失败只结束对应 Operation，不中止其他媒体或关闭执行服务；尚未开始时的失败记录没有 `startedAt`，也不会创建生成 Attempt。已接收 Operation 的短终态写入在原写者下排空，不受新工作队列满员/等候期限拒绝；同一 Operation 的并发停止共享该写入。真实持久化、清理或所有权故障仍停止执行并保留租约，不能因等候超时强制释放仍有活动工作的根。
+
+Operation字段与schema版本未改变，当前源码补全了无`startedAt`的`execution_failed`终态组合。旧候选的严格校验会拒读这一组合，回退须使用匹配版本及完整备份；回退至旧alpha.1前须核对读取能力。旧记录没有自动重写。
+
+派发时若发现另一写者占用，原 Operation 可继续保留 queued，等待用原 Key 显式接回或停止，不自动抢锁/轮询。内部 `idle()` 的一次 drain 返回不保证所有 queued 记录已终结；调用方应查看原 Operation 状态。
+
+服务启动将遗留 `queued/running` 标为 `interrupted`，不自动恢复发送。响应丢失先按原 Key 查询；需要继续时用新 Key 与当前 Run revision，保留原 Task/Attempt/连接及插件依赖。未知受理不能通过重启或换调度配置重新生成。强杀后的租约仍需按[执行服务说明](CORE_SERVICE.md)确认实际 stale PID 后恢复。
+
+工作台显示“等待远端任务名额”“等待模型冷却”“等待发送窗口”或“等待网络名额”。授权后的原 Operation 查询附带临时 `scheduling.phase`；该字段不写入持久记录。owner 的 `/api/v0/session` 另有本实例 HTTP/队列/远端数摘要；普通 MCP 不获得策略文件或管理权限。
+
+## 范围与验证
+
+该策略用于 Core 服务所装配的媒体能力、共用网络客户端的目录与供应商检测。通过同一服务接入的 Web、MCP、DSH 服务桥受同一实例约束。单次 CLI、DSH 独立原生路径、宿主借用服务及自行绕过客户端联网的可信插件，不因此获得调度承诺。没有增加后台轮询或自动恢复队列。
+
+从源码仓库运行受控本地 HTTP 和独立根用例：`tests/media-scheduler.mjs`、`tests/application-scheduling.mjs`、`tests/scheduling-policy.mjs`、`tests/scheduling-limits.mjs`、`tests/scheduling-api.mjs`、`tests/scheduling-proxy.mjs`、`tests/scheduling-recovery.mjs`；`tests/operation-runner-scheduling-failures.mjs`另覆盖排队失败隔离、终态排空和持久失败保留租约。`scripts/verify-local-web-browser.mjs --scheduling` 验证真实工作台队列提示与停止，`scripts/verify-scheduling-package.mjs` 检查实际候选 CLI/stdio MCP。这些开发脚本不随npm包分发。包验证复用已有依赖，不代表一次干净安装或真实 Agent 交付。这些验证不等于真实供应商压力、真实 Clash/TUN、ComfyUI GPU 或全部平台验收。旧百炼实验的 HTTP 峰值不能代替本片应用入口的容量证明。

package/docs/MUSIC.md

@@ -19,6 +19,8 @@ Iris 0.2.3 提供独立音乐生成能力。配置音乐模型后，可以通过
 
 配置文件中的 `musicProtocol` 使用现有标识 `gemini-web-music`，以兼容已有配置；这个标识不要求供应商或模型必须命名为 Gemini。
 
+Core 供应商页与 DSH 统一显示“Chat Completions（内嵌音频）”。模型音乐协议必须明确选择，“未指定”不会沿用供应商默认；选择协议本身也不表示该模型已经实测通过。Core 新工作台目前可配置音乐用途，音乐创作入口仍使用下方 DSH/CLI。
+
 ## 通过 DSH 或工作台生成
 
 在 DSH 中可以直接描述需求：