跳到主要内容

预设系统

预设(preset)是一组打包在一起、有名字的配置项,可以一次性应用到某个对象(标签页、Block)上, 而不用逐个手动设置。预设以 JSON 文件的形式存在,随应用一起内置,也可以按用户自行扩展或覆盖。

预设文件存放位置​

Termia 会从两个位置读取预设并合并,你自己的文件会覆盖内置的默认值:

来源位置
内置默认值pkg/wconfig/defaultconfig/presets.json,以及 pkg/wconfig/defaultconfig/presets/ 目录下的所有 *.json 文件
用户覆盖<配置目录>/presets.json,以及 <配置目录>/presets/ 目录下的所有 *.json 文件

<配置目录> 与 settings.json 所在的配置目录相同(参见 配置)—— macOS、Linux、Windows 上一律是 ~/.config/termia。如果 presets 子目录 还不存在,自己创建即可,然后按下文的格式在里面放一个 .json 文件。

两个位置的读取方式完全一样:先读顶层的 presets.json,再读 presets/ 目录下任意数量的额外文件, 全部合并在一起。这也是为什么内置预设会拆成两个文件——presets.json 和 presets/ai.json——而不是 放在一个文件里。

预设的键名与结构​

每个预设都是顶层 JSON 对象里的一个键,格式为 <命名空间>@<id>,例如 bg@midnight 或 ai@global。@ 前面的命名空间说明这个预设打算设置哪一类配置项(bg: 相关键、ai: 相关键, 以此类推);@ 后面的 id 可以随意取,应用预设时引用的就是它。

"bg@midnight": {
    "display:name": "Midnight",
    "display:order": 0.7,
    "display:mode": "dark",
    "bg:*": true,
    "bg": "linear-gradient(135deg, rgba(8, 14, 28, 1) 0%, rgba(16, 28, 56, 0.92) 45%, rgba(8, 10, 18, 1) 100%)",
    "bg:opacity": 0.95,
    "bg:blendmode": "normal",
    "bg:activebordercolor": "rgba(80, 140, 255, 0.9)"
}

有两类特殊的键前缀,不是实际的配置值:

  • display:* —— 只给界面使用的元数据:display:name(展示给用户的名称)、display:order (在选择器里的排序)、display:mode("light" 或 "dark",限制这个预设只在某个应用模式下 显示;不写则两种模式下都显示)。
  • <前缀>:*: true —— 一个"清空命名空间"的标记。应用一个带有 "bg:*": true 的预设时,会先 删除目标对象上所有已存在的 bg / bg:* 键,再写入该预设自己的键。如果没有这个标记,从一个带 bg:blendmode 的预设切换到一个不带的预设时,旧的混合模式会残留在对象上。内置的每个预设都为 自己的命名空间设置了这个标记。

预设如何被应用​

背景与外观选项展示受支持预设的生效位置。
背景与外观选项展示受支持预设的生效位置。查看原图 ↗

预设有两种应用方式:

  • 通过引用:某个配置项的值是一个预设 id——例如 settings.json 里的 tab:preset: "bg@midnight" 设置了新标签页的默认背景;ai:preset 在配置结构里也是同样的用法,作用于 ai@ 命名空间(这个命名空间目前实际由谁读取,见下文)。
  • 直接合并:界面代码读取 fullConfig.presets["bg@midnight"],把这些键直接铺到某个对象自己 的元数据上——外观标签页的主题卡片选择器就是这么做的:点击一张卡片会把预设的 bg:* 键写到工作区 里的每一个标签页上(参见 外观定制)。

本仓库实际内置的分类​

目前只有两个预设命名空间是内置的。这与早期由上游文档沿用下来的描述不同——不存在第三种"AI 聊天" 分类,因为这个应用里根本没有那个视图。

bg@ —— 标签页背景预设(在用)​

pkg/wconfig/defaultconfig/presets.json 中内置了 25 个预设,覆盖两种应用模式:16 个默认/暗色预设 (bg@default、bg@graphite、bg@midnight、bg@rainbow、bg@green、bg@blue、bg@red、 bg@ocean-depths、bg@aqua-horizon、bg@sunset、bg@enchantedforest、bg@twilight-mist、 bg@duskhorizon、bg@tropical-radiance、bg@twilight-ember、bg@cosmic-tide)和 9 个亮色预设 (bg@paper、bg@cream、bg@mist、bg@latte、bg@solar-light、bg@cloud、bg@sage、 bg@blush、bg@sand)。bg@ 预设内部使用的键:

键含义
bgCSS background 值——纯色、渐变,或两者的组合
bg:opacity背景层的透明度,0–1
bg:blendmodeCSS background-blend-mode(用于与标签页图片叠加的预设)
bg:imagefilter叠加用户图片时应用的 CSS filter(亮色预设用它给照片去饱和度,保证文字仍然可读)
bg:imageoverlay叠加在用户图片之上的额外渐变层
bg:activebordercolor该预设生效时,聚焦 Block 边框使用的强调色

外观标签页和 wsh setbg 写入的都是这个命名空间。要新增自己的预设,在 <配置目录>/presets/mybg.json 之类的文件里按同样的格式写一个或多个 bg@yourid 条目即可。

ai@ —— 存在于配置结构中,但没有任何界面读取它​

pkg/wconfig/defaultconfig/presets/ai.json 内置了两个条目,ai@global 和 ai@wave, settings.json 也把 "ai:preset": "ai@global" 设为结构上的默认值。ai@ 预设携带的是 ai:apitype、ai:baseurl、ai:apitoken、ai:model、ai:maxtokens、ai:timeoutms 这类键—— 这是一个托管聊天式 AI 服务商配置本应需要的形状。

在本仓库现状下,没有任何代码读取这些键。曾经消费 ai:preset 或任何 ai:* 键的视图已经不存在—— 它们是为已被移除的聊天视图准备的(参见 Termia Agent)。pkg/wconfig/settingsconfig.go 里还留着一个辅助方法 FullConfigType.CountCustomAIPresets,用来统计用户自定义的 ai@ 条目, 但整个代码库里同样没有任何地方调用它。请把 ai@ 命名空间当作一段惰性的配置结构,而不是一个功能: 设置 ai:preset 或新增自己的 ai@yourid 预设,在今天的应用里不会产生任何可见效果。

TT Agent 使用的 Provider/模型 是完全独立的另一套系统——在"设置 → AI"或终端块自己的菜单里选择,通过 WPS 以 agent 模型 状态的形式广播。它完全不读写 ai@ 预设。

安全地修改预设​

预设是合并而非整体替换的,所以通常不需要复制整份内置文件。要修改某一个已有预设,只需在自己的 <配置目录>/presets/ 文件里写这一个预设的键——你的条目会用相同的 <命名空间>@<id> 覆盖内置版本, 其余内置预设不受影响。要新增一个全新的预设,只要 id 不与任何内置 id 冲突即可。

目前没有应用内的预设编辑器;直接编辑 JSON 文件,然后重启 Termia,或者等待配置监听器自动感知这次 改动(应用运行期间会持续监听配置文件的变化)。