[Idea] Unified Theme Plugin System / 统一主题插件系统

[openai0229]

Status / 状态: Exploratory design proposal. Posting this discussion does not create a roadmap or release commitment.

提案状态： 初步技术方案。本 Discussion 用于收集意见，不代表已经进入路线图或承诺发布版本。

中文

适用版本

Chat2DB Community，包括 Web 和 JCEF Desktop。

问题与使用场景

Chat2DB 当前的软件界面主题、SQL 编辑器主题和终端主题是分别选择、分别维护的。用户要获得一致的视觉体验，需要在多个设置入口中自行搭配；主题开发者也无法发布一套能够完整覆盖工作区、编辑器和终端的设计。

我们希望开放主题插件能力，让社区可以编写和分享主题，同时避免通过任意 JavaScript 或 CSS 获得页面、SQL、数据源和用户数据的访问能力。

谁会受到影响

• 希望一次切换整个 Chat2DB 视觉风格的用户；
• 希望自定义背景、配色、字体、SQL 语法色和终端 ANSI 色的主题作者；
• 维护 Web、JCEF、Monaco、xterm 和设计系统兼容性的 Chat2DB 开发者。

当前替代方案

用户目前只能分别选择软件外观、Monaco 编辑器主题和终端主题，或者直接修改源码。前者容易形成不一致的视觉组合，后者不可分发、不可安全升级，也没有兼容性和回滚保证。

期望结果

用户只需要选择一个主题，这个主题同时作用于：

• Chat2DB 软件界面；
• SQL 编辑器；
• 内置终端；
• 可选的工作区背景；
• JCEF 桌面窗口的基础颜色；
• 统一的本地导入和主题管理入口。

主题开发者可以统一设计这些视觉层；Chat2DB 内部仍使用独立适配器将主题编译为 Ant Design/antd-style、Monaco、xterm 和 JCEF 各自需要的格式。

初步技术方案

1. 一个主题，一次选择

用户设置只保留两个主题相关概念：

interface ThemeSelection {
  themeId: string;
  appearancePolicy: 'fixed' | 'system';
  variantId?: string;
  revision: number;
}

fixed 使用指定变体；system 根据操作系统明暗模式在主题声明的 light/dark 变体之间切换。Auto 因此是选择策略，而不是一个独立主题。

编辑器字号、行高、Minimap、换行、快捷键、Shell 类型和终端打开位置仍是行为设置，不属于主题，也不会被主题插件修改。

2. 统一主题包，分层运行时

建议使用 .c2theme 作为主题包格式。每个主题包包含一个或多个变体，每个变体提供完整的视觉定义：

interface ThemeVariantV1 {
  baseMode: 'light' | 'dark' | 'dark_dimmed';

  ui: {
    roles: ThemeRolesV1;
    background?: BackgroundSpecV1;
    font?: ThemeFontSpecV1;
  };

  editor: {
    monaco: MonacoThemeDefinitionV1;
  };

  terminal: {
    xterm: TerminalThemeDefinitionV1;
  };

  native?: NativePaletteV1;
}

用户看到的是一个主题，开发者可以组合设计软件、编辑器和终端，但运行时不会把三种引擎的原始配置混成一个对象：

.c2theme
   -> ThemePackageValidator
   -> ThemeRegistry
   -> ThemeResolver
        |-> UI adapter: @chat2db/ui + Ant Design + CSS variables
        |-> Editor adapter: Monaco defineTheme
        |-> Terminal adapter: xterm ITheme
        |-> Background compositor
        `-> Desktop adapter: JCEF native palette

这样既能提供统一体验，也能让 Monaco、xterm 或 Ant Design 独立升级。

3. 稳定的语义主题契约

第三方主题不直接依赖 Ant Design token 名，也不使用任意 CSS 选择器。主题使用 Chat2DB 稳定语义角色，例如：

surface.app
surface.workspace
surface.sidebar
surface.panel
surface.editor
surface.grid
surface.popup
text.primary
text.secondary
border.default
accent.default
focus.ring
selection.background
status.success
status.warning
status.error

Chat2DB 将这些角色映射到当前 UI 框架。契约升级只能增加可选角色，既有角色不能改变语义；缺失角色使用主题基线的确定性回退值。

Monaco 语法规则和 xterm ANSI 16 色仍使用各自明确的数据结构，因为它们表达的是编辑器和终端独有的视觉语义。

4. 内置主题如何处理

现有 Light、Dark、Dark Dimmed 不再走一套特殊逻辑，而是注册为不可卸载、不可冒充的内置完整主题族：

builtin.chat2db
  |-- light
  |-- dark
  `-- dark-dimmed

每个变体都包含软件界面、Monaco 编辑器、xterm 终端和 JCEF 原生色。现有默认视觉在迁移后保持不变。

另提供一个最小的 builtin.recovery 恢复主题。它不加载外部资源、背景或字体，安全模式可绕过主题注册表直接启用它，避免损坏主题导致用户无法进入设置。

现有 One Dark、Dracula、Solarized 等仅覆盖编辑器或终端的配色，不再作为新的顶层独立选择。我们建议：

1. 补齐软件界面、编辑器和终端后，转换为完整主题；或
2. 仅作为旧用户迁移时生成本地个性化主题的数据来源。

5. 现有配置一次性迁入最终模型

当前已发布版本分别保存软件、编辑器和终端设置，因此升级到 Theme Platform V1 时需要进行一次迁移。该迁移直接写入最终 ThemeSelection V1 和最终主题包模型，不引入中间结构、不双写旧字段，也不留下以后还要再次迁移的过渡状态：

• 使用默认软件、编辑器和终端主题的用户直接写入 builtin.chat2db；
• light、dark、dark_dimmed 直接映射到对应内置变体；
• auto 直接映射到 builtin.chat2db + system；
• 曾经单独修改编辑器或终端配色的用户，直接生成符合最终 Theme API V1 的本地只读 Legacy Personalized 完整主题，以保留升级前的视觉组合；
• 迁移成功后删除旧主题选择字段，后续只维护最终模型；
• 用户以后主动选择其他主题时，整个软件、编辑器和终端一起切换。

Legacy Personalized 使用与市场主题完全相同的最终解析和安装模型，不是临时兼容层。字体和字号可以由主题提供默认值，但用户显式设置始终优先。

6. 背景能力

背景由 Chat2DB 自己渲染在应用内容层下方，固定为不可交互的独立平面。主题只能声明本地资源、适配方式、位置、受限透明度、模糊和明暗遮罩，不能检查 DOM、创建覆盖层或读取业务数据。

V1 建议只支持静态 PNG/JPEG/WebP。结果表、SQL 编辑器、设置页、弹窗和危险操作确认仍由 Chat2DB 控制表面透明度和最低对比度。

7. 包格式与安全边界

example.c2theme
|-- manifest.json
|-- variants/light.json
|-- variants/dark.json
|-- assets/background.webp
|-- assets/font.woff2
|-- previews/light.webp
`-- integrity.json

V1 主题是声明式数据包，不执行 JavaScript、WASM、HTML 或任意 CSS，不允许运行时远程 URL。安装时检查 JSON Schema、主题 API 版本、路径穿越、符号链接、压缩炸弹、MIME、图片尺寸、包大小和资源哈希。

主题只能改变视觉，不能改变布局结构、SQL 行为、权限、快捷键、数据库操作或网络访问。凭据输入、授权提示、危险操作确认、错误状态和焦点环保留不可覆盖的最低可见性约束。

8. 安装、预览与回滚

主题启用使用带 revision 的事务流程：

imported -> validated -> staged -> previewed -> active
                                  `-> rejected

候选主题先在伪数据预览页检查，再同步应用到 Web 渲染器和 JCEF 原生窗口。只有渲染器确认后才提交 active revision。应用崩溃、资源缺失或事务未完成时，启动过程自动恢复上一健康主题。

Web 主题资源建议存入 IndexedDB；JCEF Desktop 使用 Community 独立主题目录和内容哈希存储。运行时不直接读取主题作者提供的任意文件路径。

9. 本地导入与安装

Theme Platform V1 只实现本地主题包的导入、校验、安装和管理，不建设主题市场或在线发布链路。

本地 .c2theme
  -> ThemePackageValidator
  -> ThemeInstaller
  -> ThemeRegistry
  -> ThemeResolver
  -> 预览、启用或回滚

Chat2DB 设置页提供“内置”“已安装”两个视图和一个“导入 .c2theme”入口。本地主题与内置主题共用同一个 ThemePackageValidator、ThemeInstaller、ThemeResolver 和回滚机制，不引入临时主题格式或另一套安装链路。

本地 Theme Registry 从第一版开始使用稳定数据模型，至少包括不可变主题 ID、作者命名空间、版本、Theme API 版本、最低应用版本、许可证、变体、预览和包摘要。同一 themeId + version 对应的包摘要必须保持一致；摘要不同的包不能静默覆盖既有版本。

主题市场、上传发布、签名审核、在线更新和撤回不属于 V1。它们应在主题契约、安装流程和运行时架构经过验证后单独设计。

10. 开发者工具

计划提供：

@chat2db/theme-contract    TypeScript 类型、JSON Schema、语义角色文档
chat2db-theme create      创建主题工程
chat2db-theme validate    校验契约、安全限制和完整性
chat2db-theme preview     使用伪数据预览关键界面
chat2db-theme build       生成 .c2theme
chat2db-theme inspect     查看包能力、版本和哈希

作者工程可以用少量语义颜色生成初始 Monaco/xterm 配色，但生成的 .c2theme 必须包含完整且确定的 UI、编辑器和终端定义，确保同一版本在 Web 和 JCEF 中可复现。Chat2DB 和 CLI 必须使用同一份 contract、Schema 和校验规则。

11. V1 聚焦主题架构

Theme Platform V1 的目标是验证稳定的主题契约、安装流程和运行时架构，而不是同时建设主题分发和运营平台。工程内部可以按照依赖顺序逐步实现，但对外提供的能力必须使用同一套正式模型。

V1 必须具备：

• 最终 Theme API V1 和 .c2theme 格式；
• 内置主题与本地第三方主题共用的最终解析器；
• 稳定的主题 ID、版本和包摘要规则；
• 本地导入、校验、安装、管理和卸载；
• 预览、事务启用、自动回滚和恢复主题；
• UI、Monaco、xterm 和 JCEF 的独立适配器；
• 当前软件、Monaco、xterm 和 JCEF 配置一次性迁入最终模型。

V1 不建设临时主题格式、临时 GitHub Registry、第二套安装流程、两套主题 ID 或旧新字段双写。未来增加新的主题来源时，仍应复用 V1 的 ThemePackageValidator、ThemeInstaller、ThemeResolver 和回滚机制。

V1 完成前必须证明现有 Light、Dark、Dark Dimmed、Auto、Monaco、xterm 和 JCEF 行为没有回归，并验证本地导入、安装、启用、卸载、重启恢复和失败回滚的完整闭环。

非目标

• V1 不允许主题执行代码；
• V1 不允许任意 CSS 选择器；
• V1 不允许主题改变布局、功能或数据库行为；
• V1 不承诺动态背景、动画或远程资源；
• V1 不建设主题市场、上传发布、签名审核或在线更新；
• 本 Discussion 不代表功能已排期。

希望社区重点讨论

1. 一个主题是否应该强制包含软件、编辑器和终端三部分，还是允许构建工具自动生成缺失部分？
2. ThemeRolesV1 首期最需要覆盖哪些页面、组件和交互状态？
3. V1 只支持静态背景是否足够？
4. 是否有不依赖任意 CSS、但语义角色仍无法表达的真实设计需求？
5. 旧用户的独立 Monaco/xterm 选择应如何迁移，才能既统一入口又不丢失个人习惯？
6. 社区最希望先贡献哪些完整主题？
7. 本地导入主题需要怎样的信任提示，以及同 ID、同版本但摘要不同的包应如何处理？

欢迎主题作者、前端开发者、无障碍测试者以及 Web/JCEF 用户提出反例、样例主题和兼容性建议。在主题契约形成共识前，我们不会把它拆成 contributor-ready 实现任务。

贡献意愿

I can help implement or test this. / 我可以参与实现或测试，也欢迎社区共同完善契约和样例主题。

---

English

Relevant edition

Chat2DB Community, including Web and JCEF Desktop.

Problem or workflow

Chat2DB currently treats the application theme, SQL editor theme, and terminal theme as separate choices. Users must manually combine settings to obtain a coherent visual experience, and theme authors cannot distribute one design that covers the workspace, editor, and terminal together.

We would like to open a theme plugin ecosystem while preventing themes from gaining access to the page, SQL text, datasource metadata, or user data through arbitrary JavaScript or CSS.

Who is affected?

• Users who want to switch the entire Chat2DB visual experience at once;
• Theme authors who want to design backgrounds, UI colors, fonts, SQL syntax colors, and terminal ANSI colors together;
• Chat2DB developers responsible for compatibility across Web, JCEF, Monaco, xterm, and the design system.

Current workaround

Users must currently choose the application appearance, Monaco theme, and terminal theme separately, or modify the source code. The first option creates inconsistent combinations; the second is not distributable, safely upgradeable, or recoverable.

Desired outcome

The user selects one theme, and that theme applies to:

• the Chat2DB application UI;
• the SQL editor;
• the built-in terminal;
• an optional workspace background;
• basic JCEF desktop window colors;
• one coherent path for local import and theme management.

Theme authors design these visual layers as one product. Internally, Chat2DB still compiles the theme through separate adapters for Ant Design/antd-style, Monaco, xterm, and JCEF.

Initial technical proposal

1. One theme, one user choice

Theme-related user state should contain only a selected theme and an appearance policy:

interface ThemeSelection {
  themeId: string;
  appearancePolicy: 'fixed' | 'system';
  variantId?: string;
  revision: number;
}

fixed uses one variant. system switches between the theme's declared light and dark variants. Auto therefore becomes a selection policy rather than a standalone theme.

Editor font size, line height, minimap, wrapping, shortcuts, shell selection, and terminal placement remain behavioral preferences. A theme cannot modify them.

2. One package, layered runtimes

We propose .c2theme as the package format. Every theme package contains one or more variants, and every variant resolves to a complete visual definition:

interface ThemeVariantV1 {
  baseMode: 'light' | 'dark' | 'dark_dimmed';
  ui: {
    roles: ThemeRolesV1;
    background?: BackgroundSpecV1;
    font?: ThemeFontSpecV1;
  };
  editor: { monaco: MonacoThemeDefinitionV1 };
  terminal: { xterm: TerminalThemeDefinitionV1 };
  native?: NativePaletteV1;
}

The user sees one theme, while the runtime keeps separate adapters:

.c2theme
   -> ThemePackageValidator
   -> ThemeRegistry
   -> ThemeResolver
        |-> UI adapter: @chat2db/ui + Ant Design + CSS variables
        |-> Editor adapter: Monaco defineTheme
        |-> Terminal adapter: xterm ITheme
        |-> Background compositor
        `-> Desktop adapter: JCEF native palette

This provides one coherent experience without coupling Monaco, xterm, and Ant Design upgrades to one raw configuration object.

3. Stable semantic theme contract

Third-party themes should target stable Chat2DB roles such as surface.workspace, surface.editor, surface.grid, text.primary, border.default, accent.default, focus.ring, and status.error. They should not depend directly on Ant Design token names or arbitrary CSS selectors.

Chat2DB maps these roles to the current UI framework. Contract evolution may add optional roles but must not change the meaning of existing roles. Missing roles receive deterministic values from the selected baseline.

Monaco syntax rules and xterm ANSI colors retain explicit engine-specific structures because they represent editor- and terminal-specific visual semantics.

4. Built-in themes

Light, Dark, and Dark Dimmed should stop using a special path and become one locked, non-removable built-in theme family:

builtin.chat2db
  |-- light
  |-- dark
  `-- dark-dimmed

Each variant includes application UI, Monaco, xterm, and JCEF native colors. Existing default visuals should remain unchanged after migration.

A separate minimal builtin.recovery theme loads no external assets, backgrounds, or fonts. Safe mode can activate it without reading the theme registry, so a damaged package cannot lock the user out of Settings.

Existing One Dark, Dracula, and Solarized entries that cover only the editor or terminal should either become complete themes or remain only as migration inputs for legacy personalized themes.

5. One-time migration directly into the final model

Released versions currently persist application, editor, and terminal choices separately, so upgrading to Theme Platform V1 requires one migration. That migration writes directly into the final ThemeSelection V1 and final package model. It introduces no intermediate schema, no dual writes, and no transitional state that would require a second migration:

• default users are written directly to builtin.chat2db;
• light, dark, and dark_dimmed map directly to the corresponding built-in variant;
• auto maps directly to builtin.chat2db + system;
• users with separate editor or terminal choices receive a local read-only Legacy Personalized complete theme conforming to the final Theme API V1;
• old theme-selection fields are removed after successful migration;
• selecting another theme later changes the application, editor, and terminal together.

Legacy Personalized uses exactly the same final resolver and installation model as marketplace themes; it is not a temporary compatibility layer. Themes may provide font defaults, but explicit user font and font-size settings take precedence.

6. Background support

Chat2DB renders the background itself in a non-interactive plane below application content. A theme may declare only local assets, fit, position, bounded opacity, blur, and light/dark tint. It cannot inspect the DOM, create overlays, or access business data.

V1 should support static PNG/JPEG/WebP only. Chat2DB retains control of transparency and minimum contrast for result grids, the SQL editor, Settings, modals, and destructive-operation confirmations.

7. Package and security boundaries

V1 themes are declarative packages. They execute no JavaScript, WASM, HTML, or arbitrary CSS and may not load remote URLs at runtime. Installation validates the JSON Schema, Theme API version, path traversal, symlinks, archive expansion, MIME types, image dimensions, package size, and content hashes.

Themes can change appearance only. They cannot change layout structure, SQL behavior, permissions, shortcuts, database actions, or network access. Credential prompts, authorization UI, destructive confirmations, error semantics, and focus indicators retain enforceable minimum visibility.

8. Install, preview, and rollback

Activation uses a revisioned transaction:

imported -> validated -> staged -> previewed -> active
                                  `-> rejected

The candidate renders against synthetic data before activation. Web renderers and the JCEF native window then apply the same revision, and the active pointer commits only after acknowledgement. Missing resources, crashes, or incomplete startup transactions restore the last healthy theme.

Web assets can live in IndexedDB. JCEF Desktop should use a Community-specific theme directory with content-addressed storage. Runtime code never accepts arbitrary file paths from a package.

9. Local import and installation

Theme Platform V1 implements local theme-package import, validation, installation, and management only. It does not include a marketplace or an online publishing flow.

Local .c2theme
  -> ThemePackageValidator
  -> ThemeInstaller
  -> ThemeRegistry
  -> ThemeResolver
  -> Preview, activate, or roll back

Chat2DB Settings exposes Built-in and Installed views plus an Import .c2theme action. Local and built-in themes use the same ThemePackageValidator, ThemeInstaller, ThemeResolver, and rollback mechanism. V1 introduces neither a temporary package format nor a second installation path.

The local Theme Registry starts with a stable data model containing at least an immutable theme ID, author namespace, version, Theme API version, minimum application version, license, variants, previews, and package digest. A given themeId + version must resolve to one consistent digest; a different package must not silently overwrite an installed version.

A marketplace, publishing uploads, signing and review, online updates, and revocation are outside V1. They should be designed separately after the theme contract, installation flow, and runtime architecture have been validated.

10. Developer tooling

The proposal includes @chat2db/theme-contract for types, schemas, and semantic-role documentation, plus a chat2db-theme CLI with create, validate, preview, build, and inspect commands.

Authoring tools may derive initial Monaco and xterm palettes from semantic colors. A built .c2theme must contain complete and deterministic UI, editor, and terminal definitions so the same version is reproducible across Web and JCEF. Chat2DB and the CLI must use the same contract, schemas, and validation rules.

11. V1 focuses on the theme architecture

Theme Platform V1 validates a stable theme contract, installation flow, and runtime architecture. It does not attempt to build theme distribution and marketplace operations at the same time. Engineering may proceed incrementally according to dependencies, but every exposed capability must use the same final model.

V1 must include:

• the final Theme API V1 and .c2theme format;
• one final resolver shared by built-in and locally imported third-party themes;
• stable theme ID, version, and package-digest rules;
• local import, validation, installation, management, and removal;
• preview, transactional activation, automatic rollback, and the recovery theme;
• separate adapters for the UI, Monaco, xterm, and JCEF;
• one-time migration of existing application, Monaco, xterm, and JCEF settings directly into the final model.

V1 must not introduce a temporary theme format, temporary GitHub registry, a second installation path, two theme ID systems, or old/new field dual writes. Future theme sources must reuse the V1 ThemePackageValidator, ThemeInstaller, ThemeResolver, and rollback mechanism.

Before V1 is complete, we must prove that existing Light, Dark, Dark Dimmed, Auto, Monaco, xterm, and JCEF behavior has not regressed and verify the complete local import, installation, activation, removal, restart recovery, and failure rollback loop.

Non-goals

• V1 does not execute theme code;
• V1 does not allow arbitrary CSS selectors;
• V1 does not let themes change layout, features, or database behavior;
• V1 does not commit to dynamic backgrounds, animation, or remote assets;
• V1 does not include a theme marketplace, publishing uploads, signing and review, or online updates;
• this discussion does not imply roadmap commitment.

Questions for the community

1. Should a theme be required to include application, editor, and terminal definitions, or may build tooling generate missing sections?
2. Which pages, components, and interaction states must ThemeRolesV1 cover first?
3. Is static background support sufficient for V1?
4. What real designs cannot be expressed through semantic roles without arbitrary CSS?
5. How should existing independent Monaco/xterm choices migrate without losing user preferences?
6. Which complete themes would the community most like to contribute first?
7. What trust prompts should apply to locally imported themes, and how should packages with the same ID and version but different digests be handled?

We welcome counterexamples, sample themes, accessibility feedback, and compatibility concerns from theme authors, frontend developers, and Web/JCEF users. We will not split this into contributor-ready implementation tasks until the contract reaches community consensus.

Examples or references

The intended product experience is similar to mature IDE theme ecosystems: one installable theme presents one coherent identity, while the host application keeps renderer-specific adapters and security boundaries.

Contribution interest

I can help implement or test this. Maintainers and community members are invited to shape the contract and sample themes together.

Before posting

• I searched existing Issues and Discussions for duplicates.
• This post contains no vulnerability details, credentials, or customer-confidential information.