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

package/docs/NETWORK_RESOURCES.md

@@ -0,0 +1,106 @@
+# 出口节点与池（beta.1）
+
+0.3.0-beta.1支持独立保存和管理出口节点、出口池；供应商绑定与Doctor使用下方独立入口。**0.3.0-alpha.1 / 0.2.7 尚不包含下列命令。** 本片只管理资源，所有结果的 `routingActive` 均为 `false`；创建节点或池不会改变 Provider、Clash、进程代理或系统路由，也不会进行网络探测。
+
+本页描述v1资源。另有beta.1的[v2绑定与运行时](NETWORK_ROUTING.md)，已完成受控HTTP/HTTPS代理与原任务恢复验证；v2离线投影报告配置和 `runtimeStatus:not_observed`，不拿离线命令判断服务是否正在路由。
+
+使用本机 Core 所在环境中的绝对私有文件路径，不推断 DSH 配置或扫描代理。命令不需要 Core 数据根，不创建会话、任务或作品；owner 身份来自当前系统用户对指定私有文件的访问能力。普通 MCP 连接没有网络管理工具。
+
+## 创建与读取
+
+以下示例用于仓库源码；安装beta.1后，可将 `node bin/dsh-iris.js` 换成 `dsh-iris`：
+
+```bash
+node bin/dsh-iris.js network init --network-config /absolute/private/network.json
+node bin/dsh-iris.js network show --network-config /absolute/private/network.json
+node bin/dsh-iris.js network check --network-config /absolute/private/network.json
+node bin/dsh-iris.js network nodes list --network-config /absolute/private/network.json
+node bin/dsh-iris.js network pools list --network-config /absolute/private/network.json
+```
+
+`init` 排他创建，已有文件不会覆盖。`show` 和 `list` 返回资源及引用情况；`check` 校验本地配置，返回 `valid:true`、`networkTested:false`，不证明代理可用。未找到文件时明确失败，不自动初始化。
+
+结果中的 `revision` 是当前原文件字节的 SHA256，不是版本号。编辑时复制最近一次结果中的值作为 `expectedRevision`；成功改动返回新的修订。即使手动编辑文件时忘了增加内部计数，旧草稿也不能覆盖该编辑。
+
+## 节点与认证来源
+
+```bash
+node bin/dsh-iris.js network nodes add \
+  --network-config /absolute/private/network.json \
+  --input '{"expectedRevision":"<revision>","node":{"id":"local-clash","label":"本机 Clash","protocol":"http","host":"127.0.0.1","port":7890}}'
+```
+
+这里的端口仅为格式示例，请填写自己实际开放的代理端口。Clash mixed-port 可作为 HTTP 代理配置；本片不验证该端口，也不会调用 Clash 切组接口。
+
+节点字段：
+
+| 字段 | 约定 |
+| --- | --- |
+| `id` | 稳定身份，1–64字符，以字母/数字开头，后续可含点、短横线、下划线；编辑通过该ID选择资源 |
+| `label` | 可选单行名称，最多120字符；省略时使用ID |
+| `enabled` | 可选布尔值，默认 `true`；停用保留池引用 |
+| `protocol` | `http` 或 `https`，表示连接代理服务器的协议；这里只验证配置形状 |
+| `host`, `port` | 分开的主机和1–65535整数端口，支持域名、IPv4、IPv6；禁止完整URL、用户名密码、路径、查询和片段 |
+| `auth` | 可选 `{ "usernameEnv":"IRIS_PROXY_USER", "passwordEnv":"IRIS_PROXY_PASSWORD" }`，两项成对；不接受内联认证值 |
+
+认证变量必须来自执行命令的进程；后续服务运行时需由实际 Core 进程提供。本片不加载 `.env`，不读取其他程序的凭据。`credentialStatus` 为 `none` / `missing` / `invalid` / `ready`；`ready` 仅说明明确引用的值符合基本格式，未验证服务器认证。读取环境值只用于状态与展示脱敏，不自动写入文件或备份。资源ID、变量名和修订是管理身份，不应拿它们保存秘密；名称与展示host另作脱敏。
+
+局部编辑只改变提供的字段；省略认证保留原引用，`auth:null` 显式清除：
+
+```bash
+node bin/dsh-iris.js network nodes set \
+  --network-config /absolute/private/network.json \
+  --input '{"expectedRevision":"<latest-revision>","node":{"id":"local-clash","enabled":false}}'
+```
+
+## 固定与有序池
+
+```bash
+node bin/dsh-iris.js network pools add \
+  --network-config /absolute/private/network.json \
+  --input '{"expectedRevision":"<latest-revision>","pool":{"id":"preferred-route","mode":"fixed","candidates":[{"kind":"node","nodeId":"local-clash"}]}}'
+
+node bin/dsh-iris.js network pools set \
+  --network-config /absolute/private/network.json \
+  --input '{"expectedRevision":"<latest-revision>","pool":{"id":"preferred-route","mode":"ordered","candidates":[{"kind":"node","nodeId":"local-clash"},{"kind":"direct"}]}}'
+```
+
+`fixed` 最多1个候选，`ordered` 最多16个，原样保留用户顺序。每个候选为节点引用或显式 `direct`，禁止重复或不存在的引用，不自动补直连。上述第二个例子明确允许后续策略使用直连，请只在需要时添加；本片尚不执行候选切换。
+
+可保存 `candidates:[]` 的空池草稿；状态为 `empty`，不代表继承环境。其他状态为 `disabled`、`unavailable`、`configured`；`configured` 仅表示至少一个候选在当前配置下可选，不代表网络实测成功。显式绑定到空池、失效池时会明确失败，不偷偷直连。
+
+停用节点不移除引用；任何池（包括停用的池）仍引用该节点时禁止删除。先明确编辑候选或删除池，再删除节点：
+
+```bash
+node bin/dsh-iris.js network pools remove \
+  --network-config /absolute/private/network.json \
+  --input '{"expectedRevision":"<latest-revision>","id":"preferred-route","confirm":true}'
+
+node bin/dsh-iris.js network nodes remove \
+  --network-config /absolute/private/network.json \
+  --input '{"expectedRevision":"<new-latest-revision>","id":"local-clash","confirm":true}'
+```
+
+所有编辑支持 `--input-file /absolute/private/edit.json` 或 `--input -` 从标准输入读取。错误只报告固定原因，不回显认证URL或原始JSON。
+
+## 文件、修订与错误
+
+独立文件为 `schemaVersion:1`、初始化生成的 `configId`、单调 `generation` 和 `nodes` / `pools`；节点和池各最多256项，文件最多1 MiB。支持的格式仍属于预发布设计，未知版本或字段拒绝读取/写入，不回退、降级或自动迁移。误将 `--network-config` 指向原供应商文件也会拒绝，不修改它。
+
+文件必须为普通非符号链接文件，POSIX 下仅当前用户可读写；新文件和备份使用0600。Windows 的 mode 不等同于 ACL，应将文件放在自己的私有目录。
+
+每次实际修改在短事务锁内重新校验格式与字节修订，先保留同目录的 `.backup-*` 私有原件，再原子替换；成功才增加 `generation`。无变化不写入、不增加修订或备份。没有自动备份轮换或清理；原子替换不等于断电级 `fsync` 保证。
+
+| 错误码 | 含义及处理 |
+| --- | --- |
+| `IRIS_NETWORK_CONFIG_VERSION` | 当前程序不能解释该版本，换用兼容版本，保留原文件 |
+| `IRIS_NETWORK_CONFIG_INVALID` | 字段、引用、地址或文件结构不符合约定 |
+| `IRIS_NETWORK_CONFIG_CHANGED` | 草稿过期或读取后被改动，重新读取并核对 |
+| `IRIS_NETWORK_CONFIG_BUSY` | 文件已有 `.lock`，可能在写或有中断现场；先核查写入进程，不自动抢锁 |
+| `IRIS_NETWORK_CONFIG_IN_USE` | 节点仍被池引用，先显式修改依赖 |
+| `IRIS_NETWORK_CONFIG_EXISTS` / `IRIS_NETWORK_CONFIG_NOT_FOUND` | 初始化/添加不能覆盖，编辑/删除不能隐式创建 |
+| `IRIS_NETWORK_CONFIG_PERMISSIONS` / `IRIS_NETWORK_CONFIG_IO` | 权限过宽或文件操作失败；后者保留受控系统错误码，检查权限、空间和文件状态 |
+
+锁保护遵守本协议的写者，并在锁内检测已有外部修改；不承诺阻止绕过锁且恰好在最终校验后写入的任意外部程序。强制终止可能留锁，本片保留现场，不自动删除。
+
+v1资源管理不会修改Core根或旧Provider存储格式，也不执行路由。[N2](NETWORK_ROUTING.md)另通过显式新文件提供供应商绑定和实际代理，保留v1；[N3工作台](NETWORK_WORKBENCH.md)在独立owner开关下管理相同资源，并提供Core进程内静态/主动检测。运行时复用[实例级网络端口](PROVIDER_NETWORK.md)。

package/docs/NETWORK_ROUTING.md

@@ -0,0 +1,103 @@
+# 供应商出口绑定（beta.1）
+
+0.3.0-beta.1提供供应商绑定、HTTP/HTTPS代理、运行时与持久记录门禁，使用项目依赖 `undici@7.30.1`。**0.3.0-alpha.1 / 0.2.7 尚不包含这些增量。** 受控回环代理已验证路由、认证、失败边界和原任务跨进程恢复；这不代表所有真实供应商或系统代理均已认证。资源基础见[节点与池](NETWORK_RESOURCES.md)。
+
+## 单独启用，保留原配置
+
+v1网络资源和原供应商文件继续可用。为绑定明确新建v2，或另存复制；复制产生新configId、保留节点/池并清空绑定，原文件不改：
+
+```bash
+node bin/dsh-iris.js network routing init --network-config /absolute/private/network-v2.json
+
+# 与上面二选一：从v1/v2另存为新身份，不覆盖源或目标已有文件。
+node bin/dsh-iris.js network routing copy \
+  --network-config /absolute/private/network-v2.json \
+  --input '{"source":"/absolute/private/network-v1.json"}'
+
+node bin/dsh-iris.js network catalog create \
+  --network-config /absolute/private/network-v2.json \
+  --provider-config /absolute/private/providers.json \
+  --output /absolute/private/providers-routed.json
+```
+
+新供应商文件外层为 `{schemaVersion:1,networkRequirement,catalog}`，原供应商内容保存在catalog，目录有独立catalogId并引用network configId。旧程序看不到其要求的根部providers数组，因而拒绝使用；新版配置编辑、目录及健康写入保留包装。输出只报告身份，不显示Key。
+
+之后使用现有节点/池编辑命令配置新v2文件。v2另保存bindings，池被绑定时禁止删除；停用保留引用。创建资源或包装本身不发网络。离线资源查看只报告配置与 `runtimeStatus:not_observed`，不声称另一Core进程的实时活动状态。
+
+## 绑定具体供应商连接
+
+先 `network show` 取得最新revision；绑定使用明确的包装目录，CLI核对供应商确实存在，自动填入该目录身份：
+
+```bash
+node bin/dsh-iris.js network bindings set \
+  --network-config /absolute/private/network-v2.json \
+  --provider-config /absolute/private/providers-routed.json \
+  --input '{"expectedRevision":"<revision>","providerId":"my-provider","poolId":"my-pool"}'
+
+node bin/dsh-iris.js network bindings list \
+  --network-config /absolute/private/network-v2.json
+```
+
+模型池继续决定调用哪个服务，具体供应商连接绑定允许的出口池。不按模型品牌推断地区，不改变原媒体端点/协议摘要。新请求解析当前配置；修改网络策略后，原Task仍使用原Provider/模型/端点和远端ID。
+
+解除绑定需新revision与confirm:true。可带原包装文件，也可按bindings list给出的catalogId解除遗留引用，无须扫描或恢复已移走的文件：
+
+```bash
+node bin/dsh-iris.js network bindings remove \
+  --network-config /absolute/private/network-v2.json \
+  --input '{"expectedRevision":"<latest-revision>","catalogId":"<catalog-uuid>","providerId":"my-provider","confirm":true}'
+```
+
+明确解除后恢复继承环境；池空、停用、失效或配置身份不匹配则明确失败，不代替用户解除。绑定仍存在时删除供应商也会拒绝，先解除引用再删除。
+
+## 运行时与安全边界
+
+媒体、目录/连接检查及Core服务需显式收到同一network-config。旧供应商文件不会因为多传此参数而自动获得绑定：
+
+```bash
+node bin/dsh-iris.js run image \
+  --data-root /absolute/core \
+  --provider-config /absolute/private/providers-routed.json \
+  --network-config /absolute/private/network-v2.json \
+  --input '{"prompt":"an iris flower","model_ref":"my-provider::my-model"}'
+
+node bin/dsh-iris.js web serve \
+  --data-root /absolute/execution-root \
+  --provider-config /absolute/private/providers-routed.json \
+  --network-config /absolute/private/network-v2.json \
+  --allow-execution --allow-provider-management
+```
+
+内部实现使用实例级HTTP(S)代理客户端；未绑定继承当前fetch，明确direct使用独立dispatcher。保留宿主已配置的全局dispatcher、fetch和环境变量，不调整Clash、VPN/TUN或代理策略；不能承诺绕过系统TUN。代理认证只交给CONNECT，供应商Key不交给产物CDN。测试TLS信任只用于测试实例，产品不提供自动关闭证书校验的选项。
+
+有序主备只在独立连接/CONNECT预检阶段选择候选。一次生成及其输入准备/模型切换共享最多16次前置连接检查，同一失败路线不会随换模型反复检查。选中后才派发业务请求；POST发出后断线、超时或正文失败仍可能已受理，不透明换出口重放。已受理任务查询/下载可以在明确允许的当前策略下恢复，永不借此新生成。
+
+一个完整操作的多跳请求保持选定客户端，包括输入上传策略/对象存储及结果交付；客户端关闭等待完整操作结束。独立视觉入口尚未装配，包装目录上的视觉调用会明确拒绝，避免静默直连；原视觉配置仍可使用。DSH借用宿主模型/浏览器的出站继续由宿主管理。可信插件须消费提供的网络端口，同进程代码不受网络沙箱强制约束。
+
+beta.1中，后续解析读取到新的网络配置修订时，会移出旧修订的客户端缓存并停止它们接收新操作；当前同一供应商/调度模型身份复用一份客户端。配置未变、其引用的代理凭据值轮换时，下一次解析也会替换该身份的旧客户端。已进入完整操作的响应正文及后续请求继续使用原快照和选定路线，结束后关闭原连接池，不中途重绑或重放。保留旧客户端引用的内部调用者需重新解析，旧引用的新`run`返回`IRIS_PROVIDER_NETWORK_CLOSED`。这一回收由后续解析触发，不增加文件监听或轮询。
+
+实例关闭同时等待当前客户端和已移出缓存、仍在排空的客户端；退役清理失败在最终关闭时报告，不自动重复清理。仅继承环境的调度客户端与宿主全局dispatcher保持原生命周期，路由配置轮换不关闭宿主连接池。
+
+借用的fetch支持Node原生`Request`与`FormData`。明确direct/代理在传输边界转换到实例客户端的类型，保留multipart字段顺序、文件字节及可计算长度，不更换全局构造器；Request的覆盖参数、正文消费、重定向和取消沿用fetch语义。
+
+普通MCP不获得代理凭据或管理工具；它调用已运行Core的现有授权业务。资源Web管理与网络Doctor见[网络工作台](NETWORK_WORKBENCH.md)，需要独立owner开关。
+
+## 持久任务与兼容
+
+新网络Task从首次写入即为semanticsVersion3，Flow/创建意图首次保存networkRequirement并纳入新流程摘要。要求仅含configId/catalogId，不将节点、池版本或密码混进业务providerBinding。旧reader会在记录/版本校验处拒绝受影响记录；此机制不禁止旧writer对同根无关Artifact的任何写入。
+
+已有Task2/无要求Run继续按原配置读写；使用包装目录恢复时不会隐式升级。新Task3也不能用旧目录或另一身份配置悄悄解除要求。显式迁移旧任务尚未提供，不从当前配置补造旧出口事实。
+
+`task inspect` 可读networkRequirement和networkRoutes。路线事实在派发前由Core操作上下文持久化：configId、generation、配置摘要、catalogId、Provider、池/节点或inherit/direct、阶段与Attempt；外部传入网络管理器时也使用同一存储端口。`phase:dispatch_started`只表示客户端开始派发，不证明供应商受理或真实公网IP。`requestCount`聚合同一安全身份的顶层fetch调用，不包含CONNECT与请求实现内部重定向的全部线次数；不同事实最多128项，超出停止并保留历史，不丢旧证据。缺少持久化端口或存储失败也停止派发。
+
+## 验证范围
+
+以下测试和`scripts/`开发验收命令从源码仓库根运行，不随npm包分发；安装用户使用上方CLI/API入口。
+
+已验证本地配置/绑定、CLI/API继承路径、新记录门禁及注入transport下的主备/失败/并发隔离。实际旧代码拒绝新Task/Flow/创建意图和包装文件，原Task2仍可读取。
+
+`scripts/verify-network-proxy.mjs` 使用真实HTTP/HTTPS CONNECT代理，覆盖认证隔离、环境/宿主dispatcher并存、重定向、TLS拒绝、收到POST后断线、取消与完整正文排空。`scripts/verify-network-task-proxy.mjs` 验证Core原任务跨Node进程/允许出口恢复，以及真实CLI/API的代理生成与交付；受理未知时备用模型/出口均不重提。全部目标为受控回环服务，未调用计费媒体。
+
+轮换回归另见`tests/network-client-retirement.mjs`和`tests/network-client-rotation.mjs`：覆盖空闲历史连接池及时关闭、配置修订/代理凭据变化、旧正文与多跳保留、取消、关闭期间等待退役操作，以及释放失败保留。测试计数不代表长期RSS/文件描述符峰值或全部真实代理已认证。
+
+beta.1已另提供[出口Web管理与Core网络Doctor](NETWORK_WORKBENCH.md)，需独立管理开关；只读配置和主动GET分开。尚未验证用户真实Clash、系统TUN、住宅IP或全部供应商；标准平台按发行提交CI记录，不以此前百炼图片压测代替。SOCKS5和公开网络SDK继续后续。

package/docs/NETWORK_WORKBENCH.md

@@ -0,0 +1,65 @@
+# Core 网络出口与检测（beta.1）
+
+0.3.0-beta.1的“网络出口”页管理节点、出口池与供应商绑定，并提供实际 Core 进程内的网络 Doctor。**已发布的0.3.0-alpha.1 / 0.2.7尚不包含这些增量。** HTTP/HTTPS代理运行时见[供应商出口绑定](NETWORK_ROUTING.md)，独立资源格式见[节点与池](NETWORK_RESOURCES.md)。
+
+## 开启页面
+
+在已有Flow根启动，显式指定私有网络文件与管理开关；无需同时开启媒体执行或供应商编辑：
+
+```bash
+node bin/dsh-iris.js web serve \
+  --data-root /absolute/existing-flow-root \
+  --provider-config /absolute/private/providers-routed.json \
+  --network-config /absolute/private/network-v2.json \
+  --allow-network-management
+```
+
+按原工作台口令登录。需要编辑供应商时另加 `--allow-provider-management`；需要创作时仍使用原执行/选择开关。`session.networkManagement`独立于描述媒体权限的`readOnly`。API模式也接受该开关，普通连接、MCP的read/execute或连接管理不隐含网络管理权。
+
+网络文件不存在时，页面显示“初始化出口配置”，点击才排他创建v2。已经存在的文件不覆盖。旧v1资源和旧供应商目录不会自动迁移：节点/池仍可独立配置，绑定入口显示另存启用指引。按[绑定文档](NETWORK_ROUTING.md)在新目标创建v2和供应商包装，再正常停止并用明确的新文件启动Core；页面不会切换当前运行配置或调度重启。旧Task2继续用原配置恢复，不借新包装自动升级。
+
+## 节点、池与连接
+
+- **节点**：填写已有HTTP/HTTPS代理的主机、端口和可选认证变量名。只保存引用，由Core进程解析用户名/密码，不填写裸公网IP作为代理。停用保留池引用，被引用时拒绝删除。
+- **出口池**：固定或有序主备，明确添加候选、上移/下移、移除；直连需要主动添加。固定池最多一个候选，空池可保存草稿。绑定空池、停用池或无可用候选的池后会阻止请求，不恢复继承。
+- **供应商出口**：当前包装目录中的连接可选择池，或明确保存“继承环境”解除绑定。修改只影响后续操作的路由，不更换原任务的Provider、模型、端点或远端ID。其他目录/遗留绑定按保存身份折叠展示，可确认解除，不扫描其他文件。
+
+顶部返回和底部取消共用草稿确认。保存沿用N1/N2的修订检查、私有备份、引用保护和原子写入；外部修改时保留草稿并拒绝覆盖。保存结果不明时先重新读取，不自动重发。保存节点、池、绑定或刷新列表均不发起外部请求。
+
+模型服务卡片及功能模型池显示**配置出口**；这是当前候选的配置摘要，不是某任务已经经过该出口的证明。流程详情另显示原Task最近记录的派发路线与时间；旧任务没有记录时显示“未记录”，不会从当前池推算历史。修改配置也不会改写历史路线。
+
+## 静态检查
+
+“检测”首先只读本地事实：当前Core的平台/Node、代理环境变量是否存在、Node代理开关是否被请求，以及配置、有效候选和凭据就绪状态。不输出环境变量值、认证URL、Provider Key或上游响应正文。
+
+变量存在不等于fetch已采用它。Node22.21起可在启动时用 `--use-env-proxy` 或 `NODE_USE_ENV_PROXY=1` 请求环境代理；宿主还可能提供自己的fetch/dispatcher，因此页面分别显示开关请求与实际路径未知，不把二者等同。[Node官方说明](https://github.com/nodejs/node/blob/v22.23.4/doc/api/cli.md#--use-env-proxy)
+
+Clash与Iris池并存不是自动冲突；显式池控制Iris客户端，系统TUN是否再次接管仍是未知。Core在VPS时，检测针对VPS进程，不代表手机或电脑上的代理配置。格式、版本或权限错误不会触发修复；Doctor仍保留进程事实和可定位的错误码，资源编辑需先修正指定文件。
+
+## 主动GET与IP观察
+
+选定供应商和目标后，点击“开始检测”才联网：
+
+1. **已保存的服务地址**：无Provider Key的GET。401/403/404说明已收到目标响应，不据此断定Key错误或媒体能力不可用；这不是模型实测。
+2. **IP观察**：明确的HTTP(S) JSON目标，响应须含有效的`ip`字符串。页面提供ipify地址作为可编辑起点，点击前不会联系它；实际返回值只代表该目标此刻报告的IP，不推断地区、公网性质或所有任务的出口。
+3. **自定义GET**：明确填写不含认证信息或片段的HTTP(S) URL；不读取任意环境值、附加Provider认证或跟随重定向。
+
+每次检测总超时8秒、响应最多16 KiB、应用层最多一次GET调用；CONNECT/连接预检另受原出口策略和预算约束。响应正文不展示，结果只包含HTTP状态、耗时、是否已派发/收到响应、有限IP和本次路线。池配置失效会在业务GET前失败，不继承或直连；收到响应后的失败不透明换出口重发。
+
+检测可取消；离开页面或退出会中止等待，迟到结果不覆盖新页面。更换测试目标会清除上一项展示。检测不写供应商健康、配置、Task或作品，不安装代理、修改Clash、系统路由、环境或全局dispatcher。可信同进程插件自行联网、网关到供应商的后一段、真实TUN/住宅出口不由这些结果证明。
+
+## owner API
+
+所有接口都要求原owner认证和独立管理开关，并沿用Host/Origin、有限正文与生命周期保护。普通MCP没有这些工具。
+
+| 接口 | 行为 |
+| --- | --- |
+| `GET/HEAD /api/v0/network-management/settings` | 当前资源、目录绑定资格与连接配置路线；缺失文件不创建 |
+| `GET/HEAD /api/v0/network-management/doctor` | 当前Core进程静态事实，`networkTested:false` |
+| `POST .../init` | `{}`，排他初始化v2 |
+| `POST .../nodes/add\|set\|remove`、`.../pools/add\|set\|remove` | 原资源命令字段和`expectedRevision`；remove需`confirm:true` |
+| `POST .../bindings/set` | `{expectedRevision,expectedProviderRevision,providerId,poolId}`，只允许当前匹配目录 |
+| `POST .../bindings/remove` | `{expectedRevision,catalogId,providerId,confirm:true}`，支持明确遗留身份 |
+| `POST .../probe` | `{expectedRevision,expectedProviderRevision,providerId,target:"provider"\|"custom"\|"ip",url?}`；非provider目标须有url |
+
+资源变更返回安全投影，不返回私有备份路径或原配置。只管理本次启动明确指定的文件；HTTP请求不能选择另一配置路径。网络和供应商管理在本服务内避免交错写入；外部写入仍由文件修订门禁处理。

package/docs/PANEL_EXTENSIONS.md

@@ -0,0 +1,64 @@
+# Panel 与外观（0.3 beta，实验性）
+
+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 入口。

package/docs/PLUGINS.md

@@ -0,0 +1,193 @@
+# Core 插件贡献 v0（0.3 beta，实验性）
+
+0.3.0-beta.1 保留从alpha.1开始提供的 `@mokuyoaxis/dsh-iris/plugins` 入口及类型声明。**稳定 npm 0.2.7 没有这个入口**；示例用于beta包或当前源码；最小面见[beta约定](BETA_SCOPE.md)，完整SDK尚未冻结。兼容检查读取实际包版本，预发布标识也参与SemVer先后比较。
+
+想从一个可运行的独立项目开始，可看[插件开发与包外验收](PLUGIN_DEVELOPMENT.md)及[可复制模板](../templates/plugin-starter/README.md)。模板随beta.1分发，使用已公开的SDK，含真实对照板业务、页面、PNG 预览器和隔离自检，不安装或自动授权 harness。
+
+## 贡献与装配
+
+一个插件可组合以下贡献；它们由同一实例激活和释放。
+
+| 清单字段 | 当前已有行为 | 后续装配 |
+|---|---|---|
+| `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规则处理；支持0.3预发布的插件可明确声明 `>=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` 和beta.1的 `videoEnabled` 仅决定目录显示哪些内置分组，不能开启工作区或绕过真实根版本检查。目录快照深度只读；省略 `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)。
+
+beta.1 增加 `PROVIDER_FACTORY_CONTEXT_VERSION = 1`。统一工厂同步接收 `createAdapter(provider, context)`：Core 解析凭据到浅冻结的连接副本，`context` 只含 `{contractVersion:1, network:{fetch}, modelId?}`。完整方法的正文/多跳与关闭由 Core 管理；网络端口只在方法调用期间有效，不能在工厂或迟到后台任务中使用，也不能自行释放。公开导出相同的 `ProviderContractError` 和请求/结果类型；旧窄扩展签名保留。完整边界见[最小契约清单](PROVIDER_PLUGIN_CONTRACT.md)和[可分发 Provider 模板](../templates/provider-starter/README.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`（beta.1另有 `videoModels`、`session.video` 与 MP4/WebM 的 `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_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 客户端缓存提供。