superset-settings

用途

superset-settings 通过 superset settings 命令在命令行中管理 Superset 桌面应用的用户设置。它离线工作、无需登录，所有数据都保存在本机。所有设置命令都围绕 ~/.superset 目录（可用 SUPERSET_HOME_DIR 指向其他配置目录，便于对沙箱副本测试），并会尝试通知正在运行的桌面应用立即刷新。

主要能力

基础设置命令：

superset settings list：列出所有键、值、默认值和允许值
superset settings get <key>：获取当前生效值（未设置时返回默认值）
superset settings set <key> <value>：校验后写入
superset settings reset <key>：恢复应用默认值

主题命令：

superset settings theme list：列出系统主题、内置主题和导入的自定义主题
superset settings theme get：获取当前主题
superset settings theme set <id>：切换主题，例如 dark、light、monokai、system 或自定义 id；可用 --system-light 和 --system-dark 指定跟随系统时的明暗主题
superset settings theme export [--out]：导出完整主题 JSON 作为起始模板
superset settings theme import：添加或替换自定义主题（会校验）
superset settings theme remove：删除自定义主题

工具建议使用 --json 输出（在 agent 环境中自动开启），以解析结构化数据，并先用 superset settings list 发现可用键和允许值，而不是猜测。在 Superset 终端中，superset 已在 PATH 中。

自定义主题

有两种创建方式，最终都经过“导入 → 设置”，运行中的应用会实时换肤。

从零开始：只需一个最小文件。未指定的颜色会从所声明 type 对应的内置基础主题继承，因此可只覆盖关心的颜色：

{
  "name": "Midnight Ocean",
  "type": "dark",
  "ui": {
    "background": "#071A2E",
    "sidebar": "#061426",
    "primary": "#38BDF8"
  },
  "terminal": { "background": "#071A2E", "cursor": "#38BDF8" }
}

superset settings theme import ocean.json   # -> Imported 1 theme: midnight-ocean
superset settings theme set midnight-ocean  # a running app applies it live

从模板开始：导出某个主题的完整定义（约 38 个 ui 颜色和 21 个 terminal 颜色）再编辑，适合整体重设外观：

superset settings theme export dark --out my-theme.json
# edit, then:
superset settings theme import my-theme.json && superset settings theme set my-theme

主题文件结构：

name / id：二选一，id 会被转换为 slug（“Midnight Ocean” → midnight-ocean）；保留 id 有 dark、light、monokai、system
type："dark" 或 "light"（默认 dark），决定用于补齐省略颜色的基础主题
ui：应用外观，影响最大的键包括 background、foreground、sidebar、card、popover、primary、accent、muted、border、input、ring 以及 sidebar* 变体
terminal：xterm 颜色，包括 background、foreground、cursor、selectionBackground 和 16 个 ANSI 名称（red、brightRed 等）
editor：可选 { "colors": {...}, "syntax": {...} }，省略时根据 ui/type 生成
author、version、description：可选元数据

规则（与应用「Appearance → Import」使用同样的解析器）：所有颜色均为 CSS 颜色字符串；缺失颜色从基础主题继承；一个文件可包含单个主题、数组或 { "themes": [...] } 包；最大 256 KB；重新导入同一 id 会替换该主题；导入不会激活主题，需 theme set 激活。

验证与迭代：

superset settings theme list      # SOURCE 列显示 custom；* 标记当前激活
superset settings theme get       # 当前主题 id
superset settings theme export midnight-ocean   # 回读已保存结果
superset settings theme remove midnight-ocean   # 激活主题回退为 dark

迭代颜色时，每次导入会替换主题，运行中的应用会实时应用；循环为“编辑 → 导入 → theme set <id>”（修改后需再次 set 以重新应用当前主题）。

变更如何生效

每次写入后，CLI 会通知正在运行的桌面应用（其本地服务器上的 POST /settings-changed），应用立即刷新，包括主题，无需重启。命令输出会说明结果：“refreshed immediately” / “Applied to the running desktop app” 表示通知成功送达。以下是应用未确认时的回退行为（应用未运行或版本较旧）：

常规设置（大多数 settings set）：写入 ~/.superset/local.db。较旧的运行中应用会在窗口重新获得焦点时读取，无需重启。
Git 设置（branchPrefixMode、branchPrefixCustom、worktreeBaseDir）：通过本地 host 服务写入主机级值（通过其 manifest 鉴权，无需登录），需要桌面应用或 superset start 正在运行；同样在窗口获得焦点时刷新。
铃声注意：selectedRingtoneId 会立即改变播放的声音，但 Settings → Notifications 中的对勾标记需要应用重启后才更新。
主题（settings theme set）：通知送达时实时应用。如果输出显示回退到重启方式：先干净地退出应用，再设置，然后重新启动；较旧的运行中应用可能在其自身写入时覆盖该文件。如果你是在 Superset 终端中运行的 agent，不要自行杀掉应用（会终止你自己的会话），请让用户重启。

两个存储都由桌面应用创建。在从未运行过应用的机器上，set 命令会失败并提示先启动应用一次。

键参考（按分区）

布尔值接受 true/false/on/off/1/0/yes/no。

behavior：confirmOnQuit、fileOpenMode（split-pane|new-tab）、showResourceMonitor、showUsageInSidebar、openLinksInApp、defaultEditor（vscode、cursor、zed 等）
git：branchPrefixMode（none|github|author|custom）、branchPrefixCustom、worktreeBaseDir；主机级，通过本地 host 服务写入，因此应用（或 superset start）必须正在运行
notifications：selectedRingtoneId（shamisen、arcade、ping、quick、doowap、woman、african、afrobeat、edm、comeback、shabala）、notificationSoundsMuted、notificationVolume（0-100）
terminal：terminalLinkBehavior（external-editor|file-viewer）、terminalParkedRuntimeCap（2-64）、showPresetsBar、useCompactTerminalAddButton、autoApplyDefaultPreset、waitForSetupBeforeAgent
终端外观：terminalFontFamily、terminalFontSize（10-24，0.5 步长）、terminalLineHeight（1-2.5）、terminalLetterSpacing（-2-4）、terminalFontWeight（100-900）、terminalLigatures、terminalMinimumContrast（1|3|4.5|7）、terminalCursorStyle（block|bar|underline）、terminalCursorBlink
编辑器外观：editorFontFamily、editorFontSize、editorLineHeight、editorLetterSpacing、editorFontWeight、editorLigatures

无法通过此处设置（设计如此）：

exposeHostServiceViaRelay：安全敏感，应用将其置于计划检查和显式确认对话框之后，应引导用户到 Settings → Security
结构化设置（终端预设、agent 预设覆盖/自定义 agent、禁用的 agent 钩子）：使用 superset agents ... 或应用 UI
deleteLocalBranch 等仅存于应用 localStorage 的渲染进程偏好（diff 视图、聊天模型、热键重绑）无法从渲染进程外部访问

示例

# Dark theme with bigger terminal text
superset settings theme set dark
superset settings set terminalFontSize 16
superset settings set terminalLineHeight 1.4

# Quieter notifications
superset settings set notificationVolume 40
superset settings set selectedRingtoneId ping

# Git hygiene (host service must be running)
superset settings set branchPrefixMode custom
superset settings set branchPrefixCustom kiet/

适用场景与限制

适用于需要以脚本或 agent 方式批量调整 Superset 桌面应用外观与行为、创建并维护团队自定义主题、在沙箱配置目录中测试设置的用户。限制包括：仅管理 Superset 桌面应用自身的用户设置；部分设置（如安全敏感项、结构化设置、渲染进程偏好）不在此处开放；Git 设置和实时刷新依赖桌面应用或 host 服务正在运行；从未运行过应用的机器上写入会失败。