GUICustomization 转正实施计划（动态插件 → 组合插件）

August 14, 2026 · View on GitHub

目标见会话 goal。本文件是工程级的施工蓝图，随进度更新。

背景与结论（调研自 dsh-web-ui 参考仓库 + DSH 源码）

问题结论
组合插件挂载方式`dsh plugin --profile web add <npm包
包声明package.json "dsh": { "client": { "inject": [], "platform": "web" }, "bundle": { "patch": "./cordis.patch.yml" } } + exports["./client"]
构建管线tsdown：node 半 lib/index.js（空 apply stub 即可）+ 浏览器半 lib/client.js（window.__ModuleLoader__.load({id, factory}) 闭包工厂，CJS）
运行时外部化平台模块表（react / react-dom / cordis / ui-slots / web-react / ui-primitives / schema-form）由 loader 注入 require；其余依赖内联
CSSCSS Modules 经 lightningcss 编译 + 自动注入 <style data-plugin>；全局样式可自行注入 style 标签
背景图可见性组合版有 document：body 属性（data-guic-bg）+ 属性选择器 CSS + MutationObserver 监听明暗切换（Blue Fantasy 同款）
真·文件选择组合版有 FileReader：<input type="file" accept="image/*"> → base64 → 直接做背景，无需路径与 Host 中转
持久化组合版有完整浏览器能力：设置用 localStorage；背景图数据用 IndexedDB（绕过 5MB 上限）；跨刷新/跨重启保留

架构决策

  • 包名 @core/gui-customization，位置 CORE/packages/gui-customization/
  • 纯 Client 包：node 半为空 stub（同 blue-fantasy）；不依赖 Host 服务，零 fs/路径耦合
  • 主题应用沿用 theme.overrideTokens（alias 令牌 + 半透明化 bg-base 0.3 方案不变）
  • 默认配色 = 动态版 v7 行为（Nous 蓝 + 三预设 + 13 色 + 氛围光 + 背景图）
  • 动态版（plugins/gui-customization/，guic-3）在组合版验证通过后退役（cordis_stop），双轨台账记录映射

施工阶段

阶段 0 — 构建环境（CORE 仓库）

  1. CORE 根 package.json（private，scripts: build）+ pnpm-workspace.yaml（packages/*）
  2. pnpm add -D tsdown lightningcss + react 类型
  3. 复制构建 preset：CORE/build/tsdown.client.ts + CORE/build/web-platform.ts（源自 dsh-web-ui，BSD-3-Clause，保留署名注释）

阶段 1 — 包骨架

  • packages/gui-customization/package.json（dsh.client 声明 + exports + files）
  • cordis.patch.yml（insert 行）
  • tsdown.config.ts（clientBundle preset）
  • src/index.ts（node 半 stub：export function apply() {}）
  • src/client/index.ts（功能实现，阶段 2 填充）
  • pnpm build → 验证 lib/client.js / lib/index.js 产出

阶段 2 — 功能 TS 化 + 新能力

  1. 配色引擎：TOKEN_KEYS / DARK / PALETTES / BG_FACE_ALPHA 常量 → TS 模块
  2. 主题应用：overrideTokens + renderTheme（背景图开启时半透明化）
  3. 氛围层：shell.overlay + 光晕/呼吸/位置（v4 全套）
  4. 设置页：settings.section「界面设定」（v7 全套 UI）
  5. 持久化：localStorage 存设置 JSON；IndexedDB 存背景图 base64；启动恢复
  6. 真·文件选择：<input type="file" accept="image/*"> + FileReader → base64 → IndexedDB + 应用
  7. 背景图可见性：document.body.dataset.guicBg + 全局 style 注入 body[data-guic-bg] 规则 + MutationObserver 明暗切换 scrim
  8. 系统默认还原：清 localStorage/IndexedDB + 撤销覆盖层

阶段 3 — 挂载与验证

  1. dsh plugin --profile web add link:D:\Deploy\deepseekherness\Project\CORE\packages\gui-customization
  2. dsh --profile web --dump-config 确认挂载
  3. 重启 dsh web（用户操作桌面脚本或授权我重启）
  4. 验证清单：默认配色生效 / 设置页可见 / 氛围光 / 选文件对话框 / 背景图真正显示 / 刷新与重启后恢复 / 「设置 → 插件」区
  5. 修复迭代 → 通过后：动态版 cordis_stop 退役，双轨台账记录 v7 ↔ 组合 v0.1.0 映射

风险与对策

风险对策
npm registry 上 @deepseek-ai rc 版本与部署版本不一致纯 Client 包零产品依赖（全部经 loader/服务注入），仅构建期需要 react 类型
平台模块表与部署版本漂移复制时按部署版本核对；构建期 purity gate 会拦截非法 import
重启打断本会话挂载与构建全部完成后，重启由用户执行/授权；会话可 resume
IndexedDB API 在 DSH 页面环境受限组合版为完整浏览器环境；若异常降级 localStorage（≤5MB）并在 UI 提示