MXU Skin Protocol 0.1 草案
+
+状态：通用协议设计讨论稿，字段命名、精确 schema 和兼容性承诺尚未冻结。本 PR 另将白饭鲸鱼娘与奶蛙作为可信内置卡片接入主程序设置与任务视图（见 §9.3），不代表完整 L0/L1 运行时已经实现。配套 离线 demo 用于展示八类视觉与交互方向，不是通用皮肤运行时。
+
+1. 技术选择与职责
+MXU 已使用 React 19、TypeScript、Vite、Tailwind、Zustand，以及 Tauri 2 / Axum。建议继续使用浏览器的渲染能力：Grid/Flex 处理布局，CSS 变量处理主题，SVG、CSS animation 和 Web Animations API 处理角色与特效。第一版不需要自研绘图引擎、物理碰撞系统或另一套通用布局语言。
+皮肤描述外观、装饰位置和视觉响应；宿主维护真实控件的语义、可用状态与业务行为。启动、停止、设备选择等继续使用 MXU 的真实 React 控件，保留键盘操作、无障碍语义与既有业务判断。皮肤依赖公开契约，不依赖内部组件的 CSS 类名或 DOM 结构。
+作者提供 MXU 宿主 Web 渲染能力
+skin.json 包校验、稳定锚点 真实业务控件
+HTML / CSS / SVG / assets → 布局占位、图层合成 → 隔离装饰层
+ 受控状态与事件 Grid / Flex / CSS / SVG
+
+这里的 HTML/CSS 自定义主要指装饰场景和公开的样式变量。任意 HTML 接管应用、修改私有业务 DOM，不属于第一版皮肤能力；更高权限的应用插件应有独立契约。
+2. 能力分级与开放节奏
+
+
+
+
+| 层级 |
+作者提供 |
+表达能力 |
+建议顺序 |
+
+
+
+| L0 · Tokens |
+通过宿主注册表校验的 JSON 值 |
+明暗模式、强调色，以及逐步开放的外观参数 |
+先实现统一注入与兼容，再提供内置 token-only 皮肤 |
+
+
+| L1 · Scene |
+受限 HTML/CSS/SVG、本地资源、声明式绑定 |
+角色动画、装饰越框、布局占位、任务状态联动 |
+先以随 MXU 发布且经过审阅的内置场景验证；第三方来源等隔离与安装门槛完成后再开放 |
+
+
+| L2 · Script |
+独立授权的隔离脚本 |
+程序化角色、复杂粒子与可选 WebGL |
+仅预留；关闭 L2 不代表 L1 已安全 |
+
+
+
协议仍描述完整目标能力，但不再把“L1 的设计存在”等同于“第一阶段可以安全导入第三方场景”。建议按 L0 与宿主契约 → 内置 L1 → 第三方导入推进；具体版本号和发布时间待维护者决定。WebUI 浏览器模式默认不加载第三方场景，须单独通过其部署模式的验证。
+2.1 来源与项目打包
+这是皮肤协议，不是某一套具体皮肤。支持三种来源的目标不变：MXU 内置、各项目随项目包附带、用户自行导入。项目可以在自己的资源包中放置皮肤清单与资源，并提出默认皮肤建议；发现目录与 ProjectInterface 的对接字段尚待讨论，不在本 PR 中私自扩展 PI 协议。
+来源不扩大权限：项目附带的 HTML/CSS/SVG 也属于第三方内容，必须经过相同的校验和开放门槛。内置包同样遵循清单与资源校验，但早期只用经审阅且随程序发布的内置场景验证运行时。
+身份按 (来源, 项目标识或用户命名空间, skin.id) 隔离；只用包内 id 不能覆盖其他项目或内置皮肤。项目更新不能静默替换用户已选的另一个来源，也不能通过“内置于项目包”绕过版本锁定。
+2.2 Token 准入与优先级
+现有 applyTheme 使用 document.documentElement.style.setProperty 写入变量。L0 必须通过宿主统一的解析、合成、注入通道应用；不能让皮肤插入 :root 样式与内联变量竞争，更不能要求作者使用 !important。皮肤文档内 CSS 只影响装饰自身。
+
+
+
+
+| 类别 |
+准入与类型 |
+优先级和边界 |
+
+
+
+| 背景、正文、边框、强调色 |
+注册的语义变量；首版可只接受 #RRGGBB，拒绝 CSS 表达式、URL、任意属性名 |
+宿主默认 → 皮肤明暗默认 → 用户明确覆盖；宿主最后检查文字/控件对比度 |
+
+
+| 圆角、间距等后续外观项 |
+每项单独注册数值范围和单位；未注册则拒绝 |
+不改变控件最小点击尺寸或布局保护区；不能把“沿用变量”解释成开放任意 CSS |
+
+
+| success / info / warning / error |
+宿主拥有的状态语义，不开放任意重映射 |
+当前 success/info 跟随 accent 是既有配色策略，不是状态混淆；适配时必须保留文字/图标与可辨识性，高对比策略优先 |
+
+
+| 背景资源及透明度 |
+经包资源索引解析；透明度为有界数值 |
+用户现有背景设置继续优先；装饰与背景合成后仍需验证对比度，不能拼接原始文件 URL |
+
+
+| 明暗模式 |
+宿主解析应用设置与系统偏好后下发 data-mxu-theme |
+皮肤不得另行读取 prefers-color-scheme 决定模式，避免应用设为浅色而皮肤随系统变深 |
+
+
+| 高对比、减少动效 |
+宿主强制策略；减少动效取系统请求与应用设置的并集 |
+覆盖皮肤默认与普通用户外观覆盖，不由皮肤关闭 |
+
+
+
现有少数 dark: 样式尚可能使用 Tailwind 默认的系统媒体查询；接入前需统一应用主题属性/变体，不能声称这一点已修复。新增宿主文案须覆盖项目现有五个语言包，不能只验证中文短标签。
+3. 皮肤包与 Manifest
+拟议的 .mxuskin 是 ZIP 容器，根目录必须有 skin.json。文件扩展名只用于识别容器；清单决定格式版本。最小皮肤可以只有清单，复杂皮肤再附带场景和资源。
+little-trouble.mxuskin
+├── skin.json
+├── scene.html
+├── scene.css
+├── preview.webp
+└── assets/
+ └── mascot.svg
+
+以下清单也保存为 mascot.skin.json。它是协议示例，不是可安装成品；其中的语义锚点、槽位、场景状态及配套资源仍需宿主和皮肤作者实现。
+{
+ "schemaVersion": "0.1",
+ "id": "studio.example.little-trouble",
+ "name": {
+ "zh-CN": "捣蛋小怪兽",
+ "en-US": "Little Trouble"
+ },
+ "version": "1.0.0",
+ "mxu": {
+ "skinApi": "0.1"
+ },
+ "capabilities": {
+ "required": ["tokens.v1"],
+ "optional": ["scene.l1", "reservation.edge.v1", "bleed.stage.v1"]
+ },
+ "fallback": {
+ "mode": "tokens-only"
+ },
+ "tokens": {
+ "light": {
+ "--color-accent": "#7357d8"
+ },
+ "dark": {
+ "--color-accent": "#b6a4ff"
+ }
+ },
+ "scene": {
+ "entry": "scene.html",
+ "initialInteractionState": "rest",
+ "interactionStates": ["rest", "mischief"]
+ },
+ "placements": [
+ {
+ "id": "mascot",
+ "element": "mascot",
+ "anchor": "toolbar.primary",
+ "box": "inline-start",
+ "nudge": {
+ "inline": -8,
+ "block": 0
+ },
+ "layer": "ornament-front",
+ "bleed": {
+ "blockStart": 48,
+ "inlineEnd": 16,
+ "blockEnd": 12,
+ "inlineStart": 24
+ },
+ "hitTest": "none"
+ }
+ ],
+ "reservations": [
+ {
+ "id": "mascot-space",
+ "slot": "toolbar.actions",
+ "edge": "inline-start",
+ "size": 112,
+ "maxFraction": 0.28,
+ "when": {
+ "interaction.state": "mischief"
+ }
+ }
+ ],
+ "bindings": [
+ {
+ "event": "host.hotspot.activate",
+ "target": "mascot-poke",
+ "setInteractionState": "mischief"
+ },
+ {
+ "event": "interaction.timeout",
+ "state": "mischief",
+ "afterMs": 2400,
+ "setInteractionState": "rest"
+ }
+ ],
+ "hotspots": [
+ {
+ "id": "mascot-poke",
+ "placement": "mascot",
+ "label": {
+ "zh-CN": "让团子挤一下",
+ "en-US": "Make room for the mascot"
+ },
+ "minTargetSize": 44
+ }
+ ]
+}
+
+
+
+
+
+| 字段 |
+拟议语义 |
+
+
+
+schemaVersion / mxu.skinApi |
+清单格式版本与宿主皮肤接口版本；与皮肤自身的 SemVer version 分离。0.x 不假设跨 minor 兼容。 |
+
+
+id / name |
+稳定的反向域名式标识与本地化名称。同 ID 更新须显式选择，不能静默覆盖另一来源。 |
+
+
+capabilities.required |
+缺少任一必需能力则拒绝启用。 |
+
+
+capabilities.optional / fallback |
+缺少可选能力则移除对应表现并按清单降级；本例可保留 tokens。各能力的依赖关系须由宿主注册表定义。 |
+
+
+tokens |
+仅接受宿主注册的变量及对应类型；色值不能替换为任意 CSS。用户的明暗模式偏好继续有效。 |
+
+
+scene |
+场景入口与有限交互态列表，入口只能引用包内资源；任务态不在这里定义。 |
+
+
+placements |
+场景元素绑定到宿主扩展盒，声明小幅 nudge、图层和最大越框量；由宿主执行定位。 |
+
+
+reservations |
+向宿主边缘槽位申请布局空间。size 是请求值，maxFraction 是作者上限；宿主还要施加自身上限。 |
+
+
+when |
+只对公开字段做相等匹配，不执行 JavaScript 表达式；本例用在占位请求上。 |
+
+
+bindings |
+仅将白名单事件映射到瞬时交互态；定时器由宿主管理，不能写任务态。 |
+
+
+
hotspots 是宿主生成的真实可聚焦按钮清单，包含稳定 ID、本地化名称、目标装饰和最小目标尺寸；不是允许场景元素自行处理业务点击。44 CSS px 是建议起点，实际还受宿主布局和无障碍策略约束。空间不足或会覆盖保护区时不生成 hotspot，并在宿主皮肤控制区提供等价按钮。
+每个 placement 使用清单内唯一的 id；hotspots[].placement 引用该 ID，element 则引用场景中的装饰元素，两者不能混用。清单必须验证引用的元素、交互态、placement 与 hotspot 是否存在。缺少任一依赖能力时整组相关装饰/占位/hotspot 降级，不能留下孤立按钮或占位。下面的样式只是表现示例，省略资源引用：
+<div id="mascot" class="mascot" aria-hidden="true">
+ <div class="mascot-motion"><img src="assets/mascot.svg" alt="" /></div>
+</div>
+
+/* 均由宿主的可信渲染层投影；皮肤文件本身不运行脚本。 */
+[data-task-state='running'] .mascot-motion {
+ animation: breathe 2.8s ease-in-out infinite;
+}
+[data-interaction-state='mischief'] .mascot {
+ transform: rotate(-8deg);
+}
+[data-task-state='error'] .mascot-motion,
+[data-task-state='cancelled'] .mascot-motion,
+[data-reduced-motion='true'] .mascot-motion {
+ animation: none;
+}
+@keyframes breathe {
+ 50% {
+ transform: translateY(-6px);
+ }
+}
+
+任务态与交互态分别作用于内外包裹层。示例不再用 running → cheer → timeout → idle 共用一个状态变量：2.4 秒结束后只恢复 interaction=rest，持续任务态仍是 running。错误、取消和恢复提示优先于趣味交互。
+4. 真实占位与装饰越框
+4.1 Anchor：宿主给出可排布的扩展盒
+宿主发布语义锚点实例，至少包含 anchorId、instanceId、皮肤 generation、布局 revision、锚点矩形、允许的扩展盒与保护区。只注册当前视图中可见且有效的实例；隐藏 Toolbar、卸载节点和旧视图不能成为可选锚点。CSS 类名与 DOM 查询不是协议。
+
+
+
+
+| 字段 |
+首版候选值 |
+执行方与限制 |
+
+
+
+box |
+inline-start / inline-end / block-start / block-end / overlay |
+宿主为特定锚点发布其中的允许子集；作者在盒内用普通 CSS 排布 |
+
+
+reservations.edge |
+inline-start / inline-end / block-start / block-end |
+仅限槽位支持的边；不做任意二维碰撞 |
+
+
+placements.layer |
+background / ornament-front |
+仅是宿主开放的装饰层；popover/modal/recovery 层不能选择 |
+
+
+placements.hitTest |
+none |
+皮肤装饰不抢事件；交互由独立 hotspots 清单交给宿主 |
+
+
+nudge.inline / nudge.block |
+CSS px 数值，建议各轴限制在 -16 到 16 |
+只允许小幅视觉校正；不授予逃离扩展盒/保护区的能力 |
+
+
+bleed |
+四个非负逻辑边：blockStart / inlineEnd / blockEnd / inlineStart |
+是最多可以伸出的距离，不是任意 z-index、占位请求或输入权限 |
+
+
+
矩形使用宿主视口的 CSS px，不使用设备像素；逻辑边由宿主按方向/书写模式解释。宿主把 getBoundingClientRect() 得到的坐标转换到对应装饰层坐标，处理页面滚动、容器偏移及缩放；作者不能自行混用屏幕坐标。布局与画面都使用同一 revision 的已授予盒，旧数据丢弃。含变换容器的转换方案及几何断言需由实现验证。
+上述是待评审的最小枚举，不是已经冻结的兼容契约。
+4.2 Reservation：角色占空间，按钮真的移动
+角色进入捣蛋状态时，宿主在 toolbar.actions 的逻辑起始边插入占位轨道，让 Grid/Flex 中的真实按钮重新排布；退出后释放空间。控件的 DOM 身份、焦点与业务事件处理器保持不变。
+只给角色或按钮添加 transform 不会改变兄弟元素布局，因此不能替代真实占位。
+v0.1 建议只支持边缘槽位和面板 inset，不支持任意多边形障碍、二维碰撞或物理推挤。可用宽度不足时先缩小占位；仍不足时返回零占位，让角色移到备用锚点或隐藏。多个请求按稳定优先级分配，合计不得侵占宿主控件最小宽度。
+宿主返回实际分配的 acceptedSize 与原因，场景按实际结果摆位，不能按“申请 112 px”绘制而按钮只让出 40 px。用户正按住按钮、拖拽或进行键盘操作时，应延后布局变化，避免控件从手下移走。
+4.3 Bleed：越过面板边框，仍在应用视口内
+机甲由宿主装饰合成层绘制，跟随被锚定面板的位置，绕过该卡片及其滚动容器的裁切。此能力依赖先完成统一壳层与 portal/层叠上下文治理，不能只在现有 App 根节点插入一个高 z-index 元素。bleed 声明最大越框范围；最终允许区域取皮肤请求、宿主安全区和视口边界的交集。装饰越框不参与布局，也不会自动推开其他面板。
+overflow: visible 无法穿过 iframe、WebView 或原生窗口边界。隔离装饰 renderer 应覆盖宿主允许的 stage，不能把大角色塞进一张小卡片 iframe 后期待它自行越框。
+本提案中的“破框”指应用内面板。伸到操作系统桌面需要额外透明窗口与系统级命中处理，不属于 v0.1。
+4.4 图层、保护区与命中
+以下是需要宿主实现的目标合成顺序，不代表现有代码已有这些层：
+background → content → ornament-front → host-popover → host-modal → emergency-controls
+
+皮肤只能选择开放的层，不能提交任意全局 z-index。前景装饰默认 pointer-events: none；开始、停止、错误处理、恢复默认皮肤等保护区，以及键盘焦点环，不能被装饰遮挡。
+保护区还包括原生窗口拖动/关闭区域、右栏 resizer、Schedule/权限弹窗和被打开的菜单。宿主设备统计和任务结果不能因为皮肤构图被隐藏；窄窗口需要另有固定文本摘要。恢复入口应位于不依赖皮肤成功渲染的通路。
+“戳一下角色”由宿主创建带本地化名称、焦点环及 Enter/Space 行为的真实按钮，并验证其区域不覆盖关键控件。透明区域不应拦截指针，场景文档不得接管全屏鼠标。只有已验证的 host hotspot 事件进入 bindings，任何点击不能绕过启动/停止的既有业务校验。
+5. 状态快照与瞬时交互分层
+皮肤仅接收裁剪后的公开视图模型，不读取完整 Zustand store、任务密码、原始日志、文件路径或设备凭据。建议由宿主适配层持续投影只读快照：
+{ generation, revision, runId,
+ task: { state, progress },
+ preferences: { theme, reducedMotion },
+ layoutRevision }
+
+revision 在当前 generation 内单调递增；宿主丢弃旧快照和旧 runId 的迟到回调，创建新实例时先发完整快照。相同 revision 的重复消息不重放动画。progress 为 [0,1] 或 null（未知），不能从时间动画伪造进度或剩余时间。
+5.1 只暴露有事实来源的任务状态
+当前 TaskRunStatus 是 idle / pending / running / succeeded / failed，实例 TaskStatus 与它也不是同一层级。冻结前须建立实例/任务范围的映射表，不能把当前任务成功误当成整个队列成功。
+
+
+
+
+| 皮肤视图状态 |
+适配要求 |
+
+
+
+idle / pending / running |
+从当前运行实例、排队/启动事实派生，不能只看按钮文字 |
+
+
+success / error |
+对同一 runId 的完成结果映射 succeeded / failed，核对其是单任务还是批次结果 |
+
+
+cancelled |
+仅在适配层记录显式停止意图并确认该次运行终止后开放；当前停止清成 null 不能直接当作取消或成功 |
+
+
+paused |
+仅有真正暂停/恢复语义及事实来源时开放；当前生产适配器不能因为 demo 有暂停按钮就宣布支持 |
+
+
+
cancelled / paused 是目标能力，需能力声明或后续宿主状态机支持，不列为现有 MXU 必有状态。能力缺失时不展示相关皮肤状态；尚无法区分终止原因时显示中性的“已结束”，不能伪报成功。
+5.2 任务态不被互动计时器改写
+bindings 只改 interaction.state，不能写任务状态。最终显示由宿主任务快照与临时交互态共同决定；错误/取消/恢复提示优先，趣味动作可被抑制或清除。
+处理规则建议：快照按 revision 接收；激活 hotspot 进入 mischief 并由宿主启动 2400 ms 的交互定时器；重复激活重置同一个定时器；超时只回到 rest。进入终止态时同时取消旧定时器、恢复 interaction=rest 并释放该交互态申请的占位；切换 generation 或卸载时也清除交互态和占位。即使超时事件与任务快照同帧到达，也不影响任务事实。
+业务操作仍由真实宿主控件触发。未来如开放 requestAction("task.start")，必须校验实例、动作白名单、业务状态与真实用户手势，并继续经过既有启动流程；不开放通用 invoke、任意 HTTP、文件读写或 store setter。
+L1 作者不编写消息 SDK：可信宿主读取声明并管理布局/热点，把状态与有限属性单向投影到无作者脚本的渲染树。具体跨文档投影机制须满足第 7 节隔离门槛；不能为了接收状态就默认给不可信内容帧开放 allow-scripts。跨源、无脚本的 iframe 不能自行通过 postMessage 更新 CSS，宿主也不能直接访问其 DOM；可信控制域与内容树如何投影状态、重建是否重置动画，都需要隔离原型证明，不能把“双帧”当作现成 SDK。
+5.3 趣味反馈的组合与优先级
+新增的白饭鲸鱼娘与奶蛙场景不需要增加任务状态、执行作者脚本或把角色动作写回业务。它们分别把端碗干饭与捧腹大笑作为表现层，仍消费同一份宿主快照。推荐组合顺序如下：
+本轮两套皮肤只复用公开素材中的动作，不为角色添加对白、拟声台词或额外剧情。任务状态和互动按钮是宿主界面信息，不借角色口吻表达。
+下表包含目标协议状态和离线 demo 能力；主程序本轮内置接入仅映射已有事实支持的 idle / running / success / error，不因 demo 存在相应按钮就新增生产 paused、cancelled 或百分比进度。
+
+
+
+
+| 宿主事实 |
+角色表现与互动规则 |
+
+
+
+idle |
+可以预览吃饭或大笑；标明这是角色互动，不会启动任务。 |
+
+
+running |
+允许叠加短暂互动，但任务文字、进度和停止入口持续保留；互动结束后回到当前运行表现。 |
+
+
+paused |
+停止工作循环与持续表演，保留明确的暂停文字；不能靠改动画速度模拟业务暂停。 |
+
+
+success |
+只对已确认完成的同一 runId 显示庆祝；单任务成功不能提前触发整批完成。 |
+
+
+error / cancelled |
+清理旧互动并优先显示失败或取消；停止捧腹狂笑、吃饭庆祝等容易误读的反馈。 |
+
+
+| 恢复模式或场景不可用 |
+宿主恢复入口优先，隐藏角色并释放占位，直接使用默认外观。 |
+
+
+
进度表现只读取宿主的已知进度。progress: null 时应显示不确定状态，不能用吃饭次数、大笑次数或动画时长推算百分比、任务数量和剩余时间；也不把这些计数写成角色设定。
+交互结束、重复激活、切肤和卸载应分别测试。超时只清理其所属场景实例的 interaction，不清空任务、不重新启动任务计时器；新场景先消费当前任务快照。系统减少动效时保留静态角色、明确状态与等价热点按钮，停止摇晃、弹跳和动态视频。音频不是这两套场景的必需能力；若以后加入，须另行定义用户手势、静音偏好、停止和卸载清理，不能让主题切换触发自动播放。
+本地视频同样由宿主管理播放生命周期，不能因嵌入媒体而要求开放作者脚本或外部网络。减少动效、页面隐藏、场景卸载与终止表演时暂停视频；恢复可见时仅在当前状态仍需要表演的情况下继续。视频加载、格式或播放失败时保留本地静态图与任务文字，不阻断业务操作。媒体资源的 MIME、解码预算和来源记录仍须纳入包校验。
+6. 宿主的五项职责
+
+
+
+
+| 模块 |
+职责 |
+
+
+
+SkinLoader |
+解包、schema 校验、版本协商、资源索引与可回滚启用。安装完成不等于立即替换当前皮肤。 |
+
+
+AnchorRegistry |
+发布稳定语义锚点及矩形，用 ResizeObserver、滚动监听与合并后的帧更新同步位置。 |
+
+
+LayoutCoordinator |
+分配边缘占位、保护控件最小尺寸、返回实际分配结果，响应缩放、语言和布局变化。 |
+
+
+SkinStage |
+管理装饰图层、越框裁切、保护区、hotspot、动效生命周期与受信任恢复入口。 |
+
+
+SkinBridge |
+从 Zustand 派生只读状态，验证消息、调度声明式事件并清理卸载资源。 |
+
+
+
卸载皮肤时必须清除定时器、观察器、资源 URL、占位与事件订阅。启用与健康标记应由原生侧持久化。下一次启动在任何第三方皮肤求值之前判断安全模式，回退到内置主题；窗口显示和恢复入口不能依赖皮肤初始化完成，同时保留现有自启动隐藏窗口的用户偏好。正常换肤不能中断真实任务。
+7. 第三方导入的隔离与安装门槛
+7.1 无作者脚本不等于没有攻击面
+L1 内容文档不执行作者脚本，可信适配器、业务控件与 hotspot 留在宿主域。HTML/CSS 仍可发起资源请求、导航或造成昂贵渲染，因此只禁用 JS 远远不够。Shadow DOM 仅隔离样式；iframe 标签、CSP nonce/hash 和 origin === "null" 均不能代替权限边界。
+撤回原稿把“同文档可信 bootstrap + allow-scripts + nonce/hash”作为默认隔离方案的写法。nonce/hash 可以限制脚本执行，但不会分离同一文档中的数据与权限，也不能保护其他可达的本地 API。它并非在任何使用方式下都必然可绕过；本提案不依赖这一争论来宣布隔离成立。
+主窗 csp: null 意味着没有可继承的主窗策略；子文档仍可施加更严格策略。第三方内容应由独立资源响应提供明确、可测试的 CSP，而非只靠父文档继承或皮肤提供的 meta。若使用多帧，可信控制外壳与无脚本内容帧必须分离；双帧本身也不证明安全。
+7.2 必须验证的四条权限路径
+
+
+
+
+| 路径 |
+当前事实与开放前要求 |
+
+
+
+| Tauri 插件和原生 IPC |
+主窗有广泛文件/网络能力；ACL 与 window/webview label 和 origin 相关，DOM iframe ID 不是独立 capability 边界。独立 WebView、不同源等都只是候选手段，必须证明其拿不到宿主原生权限。 |
+
+
+| 应用自定义命令 |
+除插件 capability 外，还要核验 invoke_handler 中应用命令的授权。不能假设“不给新 WebView 插件权限”就封住全部自定义命令；需显式命令范围/来源校验或对应 AppManifest 配置并实测。 |
+
+
+| 本地 Axum / WebUI API |
+当前 Web 服务路由包含配置写入和任务控制，CORS 允许任意 origin 且该路由栈未见认证层。CORS 不是认证。要避免第三方渲染域访问控制面，需控制 API 的鉴权、授权与请求来源，并切断皮肤网络访问；不能只隐藏 Tauri 全局对象。 |
+
+
+| 资源/导航出口 |
+仅可读取包资源索引；阻止 fetch、WebSocket、图片/CSS/字体外联、表单、重定向、弹窗与顶层导航等路径，覆盖 loopback 地址和其他本地服务。资产源与控制 API 分开，皮肤不得收到控制 API 的随机会话凭据。 |
+
+
+
这里的 API 风险以应用当前权限为界；“重启为管理员”仍经过操作系统提权流程，不能表述成无条件获得管理员权限。实际 Tauri/Wry 版本与平台对初始化脚本、子帧注入有差异；源码中的 main-frame-only 标志不是跨平台隔离承诺。
+Windows WebView2、macOS WKWebView、Linux WebKitGTK，以及 WebUI 的目标部署方式，需要分别做最小隔离原型与负向测试。__TAURI__ / __TAURI_INTERNALS__ 不可见可作为检查项，但不是充分证明：还要验证原始 IPC、自定义命令和本地 API 实际被拒绝。不存在这些证据时保持第三方场景关闭。
+权限边界可对照 Tauri capabilities 文档、Tauri 2.9.5 WebView 源码与平台备注 及 CSP3 安全考虑 核对；文档说明与静态源码检查都不能替代目标平台的负向实测。
+7.3 专用安装通路
+
+
+
+
+| 边界 |
+拟议约束 |
+
+
+
+| 解包器 |
+单独实现皮肤 ZIP 导入，不复用应用升级用的通用 extract_zip，不接收 tar.gz。拒绝绝对路径、..、符号链接、重复/大小写冲突、跨平台保留名/特殊文件和超限条目；校验解码后的路径及实际写入目标。 |
+
+
+| 预算 |
+初始建议压缩 20 MiB、实际解压 60 MiB、256 文件、单文件 16 MiB；流式计算实际写入字节，不能信任 ZIP 头中的长度。限制节点、像素解码量与昂贵 CSS 效果。 |
+
+
+| 内容 |
+校验实际 MIME；SVG 移除脚本、事件、外链和 foreignObject；用成熟解析器及 allowlist 处理 HTML/CSS，遍历嵌套规则、URL、字体和 @import，不用正则代替消毒器。 |
+
+
+| 内容身份 |
+计算实际包/版本内容摘要，完整性校验覆盖保存与读取；摘要只有和可信来源记录绑定才提供来源保证，不把作者自报哈希当签名。 |
+
+
+| 安装/启用 |
+暂存校验 → 不执行未批准内容的预览 → 写入不可变版本目录 → 原子更新启用记录。使用独立皮肤目录和版本清单，不用符号链接表达 current。失败保留上一个可用版本。 |
+
+
+| 回滚与清理 |
+建议至少保留最近两个已知可用版本；回滚记录与健康标记不放到现有启动清理的临时更新目录。清理必须理解引用关系，不能删除当前/回滚版本。 |
+
+
+| 更新 |
+首版不做自动或静默皮肤更新；新版本重新校验、显式启用，用户选择锁定来源和版本，不能借更新增加权限。 |
+
+
+
当前应用更新工具支持的归档类型与校验预算不等同于皮肤安装要求；本 PR 不顺带改造应用更新系统。内置和项目附带的资源仍走对应校验，来源不豁免内容约束。
+7.4 开放第三方场景的验收门槛
+以下全部完成后再讨论默认启用：隔离域三平台负向实测；原生 IPC/自定义命令/控制 API 权限隔离及网络出口限制；专用解包与资源校验；不依赖皮肤的原生启动恢复；锁定版本、显式更新与回滚。WebUI 另做独立验收。L2 需要重新评审，不是给 L1 随手添加一个 allow-scripts 开关。
+8. 兼容、降级与动效预算
+宿主先检查 schema 与必需能力，再检查锚点。当前视图暂时没有某个锚点时，隐藏对应装饰并释放占位。缺少可选场景能力可以降为 L0；未知必需能力必须拒绝。新增字段需在 schema 中明确标为可选，不能静默容忍字段拼写错误。
+基础方案优先使用 Grid/Flex、CSS 变量、SVG 与经典关键帧。CSS anchor positioning、复杂滤镜、WebGL、Lottie/Rive 等可在有实际需求时作为独立能力与适配器添加，不把协议绑定到某个动画库。
+
+- 可操作性：保留文字、键盘焦点、足够对比度与直接操作入口。纯装饰对读屏隐藏；hotspot 具有名称和键盘行为。
+- 减少动效：尊重系统
prefers-reduced-motion 与 MXU 手动设置。关闭循环弹跳、强闪光、大幅视差；静态模式仍表达任务状态。
+- 布局预算：只在状态变化时调整占位，避免每帧重排模拟物理。指针交互期间延后移动关键控件。
+- 动画预算：初始建议最多 4 个持续动画角色；状态与锚点更新合并到每帧一次。离屏、隐藏窗口与后台暂停表演。
+- 退化路径：持续超预算时关闭昂贵滤镜/粒子、改静态图，最终卸载场景保留 tokens。JS watchdog 不能中断任意 CSS 渲染卡顿，导入前还需限制节点与昂贵效果。
+
+这些数值是实现起点，不是测得的性能承诺。验证需覆盖五种语言与长标签、850×525 最小窗口、125%/150% 缩放、面板折叠、移动 WebUI、减少动效与运行中换肤。需要真实浏览器/WebView 的静态布局 harness 验证扩展盒、碰撞与焦点/点击保护区；jsdom 无法证明这些几何性质。字体、字重与颜色组合须以可读性和 WCAG 对比度检查验收，不能把示意图的小字号当产品规范。
+9. 接入现有 MXU 的前提
+下表以本设计 PR 的基线 a05a112 说明通用皮肤运行时的接入前提。§9.3 单独列出本轮已实现的两套可信内置卡片；不能将该有限接入当作表中全部改造已经完成。
+
+9.1 偏好与版本的存储域
+桌面现有外观配置是按项目保存，WebUI 有独立的 origin-local 外观偏好且不会直接回写覆盖桌面。这些行为应保留兼容，不能新增一个全局 activeSkinId 后默默改变用户的项目偏好。
+建议明确区分桌面本机默认、用户对特定项目的显式覆盖，以及项目包的推荐值。初次启用项目皮肤需要用户选择“跟随项目推荐”；没有选择时不因项目更新强制换肤。解析优先级为用户项目覆盖 → 用户本机默认 → 已授权跟随的项目推荐 → MXU 内置回退。记录来源与版本，项目身份需稳定且可迁移。
+WebUI 的选择仍是该浏览器客户端的偏好，不广播到桌面或其他浏览器。已有后端配置 revision/CAS 可复用到其实际负责的设置域，不需要另造一套全局写入机制；皮肤公开状态的 generation/revision 是运行时消息时序，与持久配置 revision 不混用。切项目与多客户端并发策略需在实现前固定。
+9.2 建议的实施顺序
+
+- 先补 token 注册/优先级、统一壳层与图层计划、VM 事实映射和恢复设计；内置 L0 可先落地。
+- 实现稳定锚点、扩展盒与占位、宿主 hotspot，在经审阅的内置 L1 上验证各类表现。
+- 提供浏览器/WebView 布局 harness，测试最小窗口、缩放、语言、滚动、折叠、热点与运行中换肤。
+- 完成第 7 节全部门槛后，才开放项目附带/用户导入的第三方场景；WebUI 单独放行。
+- 有不可由 L1 表达的实际需求时，再设计 L2。
+
+具体版本节奏待讨论，本稿没有将上述步骤变成发行承诺。所有新增宿主界面文案使用既有 i18n 体系。
+9.3 本轮可信内置皮肤接入
+主程序设置的外观分区增加默认、蓝色大肥鱼吃白饭、奶蛙三项选择，以及皮肤减少动效偏好。原有明暗模式、强调色、自定义强调色和背景图继续独立生效；内置皮肤选择不通过改写用户强调色实现。
+skinId 仅接受 default / deepseek / naiwa，未知或旧配置中缺失的值回退为默认；skinReducedMotion 与系统减少动效请求共同约束角色表现。桌面沿用现有项目外观配置，WebUI 沿用本地外观存储及后端值缓存，避免浏览器本地选择回写覆盖桌面偏好。这不是第 9.1 节完整多来源、项目推荐和版本管理方案。
+BuiltinSkinCompanion 由宿主 React 代码和前端随包资源实现，在主视图两个可见工具栏位置之前使用普通文档流卡片，设置页提供预览。默认皮肤不渲染角色。它不依赖隐藏 Toolbar 实例，不接管业务控件，也不创建任意高 z-index 覆盖层；图片、视频仅负责装饰，互动使用宿主真实按钮。换肤只卸载或更新表现，不改任务 store、启动流程或停止流程。
+生产任务状态读取活动实例：isRunning 优先映射运行中，再将整批 Succeeded / Failed 映射成功 / 失败，其余中性显示为待机。停止流程清成 null 不被解释成成功或取消；不从单任务状态、动画时间、饭量或笑声计算百分比。角色临时互动只更新组件本地状态，不能覆盖当前任务事实。
+资源固定来自 src/assets/skins/，不支持作者提供 HTML/脚本、不解释 .mxuskin、不提供第三方安装入口，也不增加原生或网络权限。媒体来源说明见 两套皮肤说明。本轮验证可信内置场景在现有宿主中的选择、持久化和真实布局，通用 token registry、Manifest 绑定、稳定锚点、保护区裁切与隔离门槛继续保留。
+鲸鱼娘采用固定版本社区吃饭动画，原 VP9 alpha 经解码合成白底、移除音轨并转为 H.264，静态姿态从同源视频抽帧保留透明，本次不重绘角色。格式不受支持或播放失败时保留静态表现；不能以 Chromium 成功播放推断所有原生 WebView 都已通过验证。资产的 CC BY-NC-SA 4.0、署名与修改记录独立于代码许可。
+10. 离线 Demo 能证明什么
+八个离线场景分别展示角色占位、机甲越框、生态舱生长、黑胶旋转、完成印章、声呐扫描，以及白饭鲸鱼娘与奶蛙的趣味互动；另提供成功/失败/取消/重试的任务模拟、稳定的宿主状态摘要、进度条语义、宿主按钮热点、布局轮廓、减少动效、有限预设导入导出和 24 条扩展创意。它们用于讨论表现力、协议范围与操作手感；主程序本轮只接入 §9.3 的两套内置皮肤。
+需要明确区分：
+
+- demo 是可信内置场景与本地模拟任务，未连接 MaaFramework，没有执行真实设备操作。demo 自己的暂停/取消/失败状态不代表现有生产 store 已提供同样事实。
+- 角色交互使用演示器拥有的真实 button，可由键盘激活；它展示宿主拥有交互语义，但尚未证明动态定位、保护区命中或跨隔离域消息安全。
+mxu-skin-demo/0.1 仅包含名称、八种内置场景选择、受限十六进制色值、数值参数和效果开关；它不执行导入 HTML/CSS/JS，不是 .mxuskin 安装器。- 原六场景使用手动预览开关；其中团子的 Flex 占位证明真实重排，但未执行 Manifest 示例中的 2400 ms 自动复位。新两套白饭鲸鱼娘与奶蛙由演示宿主管理 2400 ms 互动计时器，重复触发只重置同一计时器，超时不改任务状态或进度，暂停与终态清理互动。它们尚不是正式 Manifest 绑定解释器；完整分配结果回传、交互期间延后移动、保护区裁切和隔离导入仍需宿主实现。
+- 奶蛙大笑使用包内无音轨视频，始终设为静音、循环和内联播放；仅角色互动或成功反馈需要表演时播放。减少动效或页面隐藏时暂停，
pagehide 清理互动并停止、复位视频，pageshow 仅按当前状态恢复。播放失败时退回静态姿态与文字；闭口静态姿态直接取自原片第 1 秒。原片、海报及静态截帧的来源记录见 两套皮肤说明。
+- 鲸鱼娘吃饭使用既有社区视频转成的白底无声 H.264，并以同源透明抽帧作为静态姿态；它与奶蛙都没有角色对白。媒体来源、许可、作者署名和实际处理单独记录，不以代码许可替代资产许可。
+- demo 切换场景会重置模拟任务；生产换肤必须保持业务任务继续执行。
+- 概念切片与 Manifest 示例不是完整规范对象或可安装成品。
+- 静态设计图不是 MXU 实机截图。已完成的 DOM/事件检查不等于浏览器视觉、CSS 几何、跨平台或生产隔离验证。
+
+11. 待讨论与冻结事项
+正式实现前仍需共同决定（本文候选字段仍需 schema 与原型验证）：
+
+- L1 是否只承担装饰和主题，还是需要受控的业务卡片模板？完整布局替换是否另设能力？
+- 锚点、槽位、公开状态和能力注册表的最小集合，以及缺失能力的依赖降级顺序。
+- 本文新增的最小候选枚举、分层状态与 hotspot 字段是否合适；仍需正式 JSON Schema、完整错误诊断与兼容性测试。
+- 各平台隔离 renderer 的具体实现和原生权限验证方法。
+- 多占位请求冲突、长标签与窄窗口下的布局分配规则。
+- 作者预览、调试工具、静态打包与资源预算如何做得足够简单。
+- 第一批内置皮肤优先验证哪些玩法，哪些效果值得先做成官方可复用组件。
+
+欢迎在设计 PR 中补充想法、替代方案、示意图或具体皮肤需求；本稿的目标是把讨论变得具体，不是提前冻结实现。
+ 
+ 
+ 
+