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

package/docs/LOCAL_WEB.md

@@ -0,0 +1,201 @@
+# 本地 Core 工作台（0.3 alpha）
+
+第一次使用可从[空配置快速开始](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 不包含。** 以下命令使用源码树；安装alpha包后将 `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)。
+
+ComfyUI 供应商支持 API 图/v0/v1 模板导入、开放参数及表单预览。创作时按明确模板显示 LoRA 双权重、种子和其他控件，LoRA/更多参数默认折叠，检查更新保留用户已展开的区块；结果详情显示原 Run 的参数快照。节点检查需要单独开启供应商管理，执行权限不会自动获得管理能力；见 [ComfyUI 使用](IMAGE_GENERATION.md#comfyui-入口)。
+
+## 能力总览
+
+侧栏“总览”或 Iris 标志进入六类能力卡片：图片、视频、语音、音乐、转写、视觉。也可在已有工作台地址后添加 `/#overview` 直接定位，登录与刷新沿用现有标签页会话；普通入口与 Run 深链接继续保留原创作行为。
+
+上方显示当前服务是否允许创作、图片/音频目录中的模型候选去重数，以及当前工作区的实际流程数。卡片分别呈现入口覆盖、已保存用途/功能池、当前候选和历史实测；标注用途与过去成功不等于现在可调用。实测记录只有在 owner 供应商管理已开启且读取成功时可见，其他会话标明“未提供记录”。读取失败显示未知，不当作零配置或成功；刷新不会读取远端模型目录或发起实测。
+
+图片、语音、转写卡片仅在当前根、执行权限与实际候选满足时启用对应创作按钮，点击只打开真实草稿，不提交任务。语音与转写需要 v3 根；视频、音乐、视觉注明已有 CLI/DSH 入口及 Core Web/MCP 待接入范围。配置按钮只跳转已开启的模型服务页，不自动启用功能或改变授权。
+
+“更多 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 根另开放语音和转写，视频、音乐、视觉标为未接入。工具细选默认折叠，操作权限与功能分开。默认只读服务只能分配 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、同页新链接、重启失效与新链接接回、取消迟到兑换、禁用存储和坏片段；不提交媒体或管理写入。与其他场景开关分开使用。
+
+`--audio` 单独验证新 v3 根上的 TTS、音频导入/转写、原 Task 明确观察、音频实际解码/播放、WAV与UTF-8下载、刷新零重提、创建回包丢失、作品分类、只读以及桌面/窄屏/主题。Provider 使用受控响应，不等同于真实付费服务验收；边界与对应定向测试见[音频流程](AUDIO_FLOWS.md)。
+
+`--overview` 单独验证六类能力、旧根/音频根与只读边界、四种草稿跳转、历史实测、未知/失败状态、刷新保留供应商草稿、明确保存后的同步和手机/明暗布局。使用隔离配置与受控执行端口，检查浏览/刷新与草稿跳转不写 Core、不调用供应商；不与其他场景开关组合。
+
+源码已把 [有限执行](CORE_SERVICE.md)、[持久选择](LOCAL_SELECTION.md)、[原身份恢复](WEB_RECOVERY.md)、文生图及供应商设置接到真实页面，并补充本机受控验证。标准平台、真实设备和发布前完整验收仍待完成，历史完整门禁停滞继续单独调查；其他媒体和最终演示素材按 [路线图](ROADMAP.md)推进。本页实现未发布，也不等于生产环境或真实付费验收完成。

package/docs/MCP.md

@@ -0,0 +1,191 @@
+# 通用 MCP 接入与能力选择（0.3 alpha）
+
+新用户先看[从零启动与页面接入](CORE_QUICKSTART.md#connect-an-agent--连接客户端)；交给安装/使用 Agent 的可复制说明见 [Agent Core 指导](AGENT_CORE_QUICKSTART.md)。本页详述传输、模板与授权契约。
+
+同一套 Iris MCP 工具可通过 stdio 或 Streamable HTTP 接入支持对应传输和协议的客户端。无需为每个产品编写 Adapter，客户端名称也不用于授予能力。**本页入口从0.3.0-alpha.1提供，稳定 npm 0.2.7 不包含**；安装准确alpha版本或使用当前源码，契约仍为实验性。
+
+业务数据、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` 新根，原根不迁移。
+
+工具输入、功能归属、权限和指导来自同一 [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)。
+
+## 首次接入与客户端预设
+
+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`，根版本进一步限制实际可用分组；查看工具总目录：
+
+```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 根开启。
+- `--capabilities transcribe`：实际转写候选、原音频导入/来源ID创建、音频与文字读取及共享 Run/Operation 工具；仅在 v3 根开启。可用 `tts,transcribe` 同时选择。
+- `--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 登录或自动端口发现。
+
+当前每项 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 根，持久来源与原任务恢复 |
+| 视频/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 alpha源码能力。
+
+文生图连接的 Skill 对 ComfyUI 先确认缺少的工作流、LoRA 与参数要求，再使用实际目录中的 `modelRef` 和 `comfyWorkflow.parameters`。目录工具、执行工具或改图工具未开放时，说明会相应限定调用和搭配，不提供越权的替代路径。当前可将 ComfyUI 输出作为同根作品交给支持改图的 API，反向图片输入尚未接入；详见 [ComfyUI Skill 参考](../skills/iris-core/references/comfyui.md)。

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 中可以直接描述需求：

package/docs/PANEL_EXTENSIONS.md

@@ -0,0 +1,64 @@
+# Panel 与外观（0.3 alpha，实验性）
+
+Core 的 API、CLI、MCP 不依赖页面。`web serve` 默认装配随包的 `iris.default-panel`，也可在启动时明确选择可信 Panel。它与 [Provider 扩展](PROVIDER_EXTENSIONS.md)使用不同契约。**npm 0.2.7 尚不包含这些入口**，契约版本为 `0`，尚未冻结为 SDK。
+
+[Core 插件贡献 v0](PLUGINS.md#web-贡献和生命周期)支持默认 Panel 的页面、设置表单和作品预览组合。装配时按完整贡献 ID 明确选择，复用主题、当前登录与 Core API；安装不自动启用。设置默认折叠，预览按实际 MIME 选择，导航/退出释放挂载。可经实验性公开 `createCorePluginWorkbench` 装配已有根；此入口的媒体只读，供应商管理须另行开启。CLI 仍用下面的原独立清单替换整套 Panel，与组合选择互斥；本地主题不变。
+
+## 默认外观
+
+默认浅色、白色主体，鸢尾渐变只用于细线和小面积点缀：
+
+```css
+linear-gradient(105deg, #45317D, #6F69B8, #BB78AD, #E59B76, #ED9C91, #F0D09C)
+```
+
+右上角“外观”统一提供浅色、深色、跟随系统和舒适/紧凑布局，顶栏不再提供重复明暗按钮。点缀固定使用鸢尾，移除仅小幅改变按钮/选中色的紫罗兰、玫瑰、杏色选项。展开“自选背景”可使用本地 PNG/JPEG/WebP（最多 5 MiB），调整位置、遮罩和模糊。即时预览，图片比较区保持独立中性底色。
+
+配色与布局保存在当前 origin 的 localStorage，背景 Blob 保存在 IndexedDB，不上传 Core、不进入作品库。不同浏览器、端口和设备不自动同步；清除站点数据可能清除此偏好，它不是图片备份。存储失败时提示，本次预览仍可使用。Token 和供应商密钥不进入这些存储。
+
+“恢复默认配色与布局”只恢复显示参数；“移除背景”单独移除此浏览器的背景。展开“分享外观设置”可导入/导出以下受限 JSON，不包含图片或认证，不支持任意 CSS/脚本或远程背景 URL：
+
+```json
+{
+  "contractVersion": 0,
+  "theme": "light",
+  "accent": "iris",
+  "density": "comfortable",
+  "position": "center",
+  "overlay": 86,
+  "blur": 0
+}
+```
+
+`theme` 为 `light/dark/system`，新设置的 `accent` 固定为 `iris`，`density` 为 `comfortable/compact`，`position` 为 `center/top/bottom`。读取或导入旧 v0 的 `violet/rose/apricot` 时只把点缀归一为鸢尾，保留明暗、布局、背景参数；不会自动覆盖原文件。遮罩为整数 50–100，模糊为整数 0–20 像素。未知字段/版本拒绝导入，保留当前设置。这是默认 Panel 的主题格式，不表示替代 Panel 必须提供相同控件。
+
+## 显式选择替代 Panel
+
+自行审查并准备本地目录；Iris 不扫描、下载依赖或自动安装。目录中放置 `iris-panel.json`：
+
+```json
+{
+  "contractVersion": 0,
+  "id": "example.my-panel",
+  "version": "1.0.0",
+  "assets": {
+    "/": "index.html",
+    "/main.js": "main.js",
+    "/theme.css": "theme.css"
+  }
+}
+```
+
+```bash
+node bin/dsh-iris.js web serve --data-root /absolute/existing-flow-root \
+  --token-file /absolute/new-owner-token \
+  --panel /absolute/trusted-panel/iris-panel.json
+```
+
+资源从清单目录解析，启动时固定为有限快照：最多 128 项，单项 8 MiB、合计 16 MiB。必须声明 `/` HTML；目录逃逸、API/MCP 路由映射、符号链接逃出资源根均拒绝。未声明文件不公开，请求路径不拼接磁盘目录，不支持热更新。HTML 使用外部 `script src` / `link href` 引用资源，遵守现有同源 CSP；内联或远程脚本不开放。清单只应列公开页面资产，不能包含私有配置。
+
+替代 Panel 通过同源 `/api/v0/session` 获取版本和能力，API 仍要求 Bearer、Host/Origin 与明确权限。会话 `panel` 只返回 id/version/contractVersion，不返回清单路径。不启用工作台时 API/MCP/CLI 仍可独立运行。
+
+**可执行 Panel 必须可信**：页面代码能接触交给它的会话 Token，并调用 owner 已获授权的 API。清单是加载边界，不是代码沙箱；纯主题 JSON 没有这些执行能力。DSH 内嵌工作台仍由宿主装配，此处设置不会自动应用到 DSH。
+
+默认 Panel 处理[访问口令](WORKBENCH_LOGIN.md)。替代 Panel 启用口令模式时，应读取 `GET /api/v0/workbench/auth`，首次设置立即清除 `#setup=…`，使用同源 `/setup`、`/password-login`、`/logout` 及独立浏览器 Bearer；记住设备、退出撤销及恢复遵循[接口与装配](WORKBENCH_LOGIN.md#接口与装配)。后端仅为默认 Panel 标注模式，不向替代页面注入凭据或登录代码。若替代 Panel 仍只支持旧接口，应显式用 `--token-file` / `--token-dir` 启动：清除 `#login=…` 后用同源 `POST /api/v0/workbench/login` 兑换浏览器 Bearer，或使用原 Token 入口。