深入解析 Tabby 的 tabby-core 插件：七项核心服务与插件扩展 API

本文围绕 tabby-core/README.md 展开，系统讲解 Tabby 终端最底层的内置插件 tabby-core 所提供的七项核心能力——标签页界面服务、工具栏 UI、配置文件管理、快捷键、标签恢复、日志与主题，并结合仓库源码给出每项能力对应的服务类、API 抽象与注册方式。读完本文，你既能看懂 Tabby 插件体系的整体骨架，也能照着 README 中的 @NgModule 示例正确地把自定义子类导出给主应用。

模块定位与打包方式

tabby-core 是 Tabby 的"地基"插件，README 明确列出它提供以下能力：

• tabbed interface services（标签页界面服务）
• toolbar UI（工具栏 UI）
• config file management（配置文件管理）
• hotkeys（快捷键）
• tab recovery（标签恢复）
• logging（日志）
• theming（主题）

从 tabby-core/package.json 可以看到它的打包与依赖事实：

• name 为 tabby-core，main 指向 dist/index.js，typings 指向 typings/index.d.ts，插件消费方拿到的就是编译产物加类型声明；
• keywords 中包含 tabby-builtin-plugin，这是 Tabby 内置插件的标识；
• peerDependencies 锁定 @angular/core 等 Angular 15 全家桶与 rxjs ^7，说明整个插件体系构建在 Angular 依赖注入之上；
• 本地 devDependencies（js-yaml、deepmerge、uuid、fuzzy-search、bootstrap 等）则与下文"配置文件管理""标签恢复"等实现细节一一对应。

需要说明的是，README 开头的 "See also" 列出了 settings/、terminal/、local/、linkifier/ 四个相对目录链接；这些目录在当前仓库中已不存在，相应能力如今由仓库根目录下的独立内置插件 tabby-settings/、tabby-terminal/、tabby-local/、tabby-linkifier/ 承担。因此本文以 tabby-core 自身源码为准。

一、标签页界面服务：AppService 与 TabsService

这是 tabby-core 对外暴露面最大的一块。README 给出的示例 import { AppService, TabContextMenuItemProvider } from 'tabby-core' 中，AppService 就是标签页管理的入口，实现位于 tabby-core/src/services/app.service.ts。从源码结构看，它是 providedIn: 'root' 的单例（构造器被标记为 private），维护一个 tabs: BaseTabComponent[] 列表，并以 RxJS Subject 形式向外广播 tabOpened$、tabClosed$、tabRemoved$、activeTabChange$、tabsChanged$ 等事件流，供工具栏、快捷键和其他插件订阅。

关键行为都有明确实现依据：

• 打开标签：openNewTab(params) 会先用 TabsService.create 实例化目标组件，再包一层 SplitTabComponent 加入顶层列表；openNewTabRaw 则跳过这层包装。插件若要直接开一个终端/SSH 标签，走的就是这条路径；
• 焦点与标题联动：selectTab() 在切换时向旧标签发出 emitBlurred()/emitVisibility(false)，在新标签上延迟发出 emitFocused()/emitVisibility(true)，并把当前标签标题同步到窗口标题；
• 循环与重排：nextTab()/previousTab()、moveSelectedTabLeft()/moveSelectedTabRight() 的行为受配置项 appearance.cycleTabs 控制（是否首尾循环），且 swapTabs() 会拒绝跨"固定/未固定"边界的交换——固定标签只能在前 getPinnedTabCount() 个位置内移动；
• 关闭与重开：closeTab() 在销毁前会调用 tabRecovery.getFullRecoveryToken(tab, { includeState: true }) 生成恢复令牌，压入 closedTabsStack 并截断为最近 5 条（见 app.service.ts），reopenLastTab() 即从这个栈弹出令牌恢复标签。

窗口级行为也集中在这里：当 appearance.lastTabClosesWindow 为真时，关闭最后一个标签会触发 hostWindow.close()；closeWindow() 则会先禁用恢复、保存全部标签、再逐个 destroy(true)。explodeTab()/combineTabsInto() 则负责把拆分标签拆成多个顶层标签、或把所有标签合并进一个拆分容器，后者用 Math.ceil(Math.sqrt(n + 1)) 的步长近似排成方形布局。

二、工具栏 UI：ToolbarButtonProvider

README 提到的 "toolbar UI" 对应的扩展点定义在 tabby-core/src/api/toolbarButtonProvider.ts。ToolbarButton 接口的每个字段都有文档说明：

字段	类型	含义
icon	string	原始 SVG 图标代码
title	string	按钮标题（必填）
touchBarNSImage / touchBarTitle	string	可选的 macOS Touch Bar 图标 ID 与按钮文案
weight	number	排序权重
click	() => void	点击回调
submenu	() => Promise<ToolbarButton[]>	异步生成子菜单，支持递归嵌套

插件只需继承抽象类 ToolbarButtonProvider 并实现 provide(): ToolbarButton[]，即可向工具栏注入按钮，且子菜单可以无限嵌套。

三、配置文件管理：ConfigService 与 ConfigProvider

这是 tabby-core 中最"厚"的一块。配置服务实现于 tabby-core/src/services/config.service.ts，对外核心是三个东西：store（实际配置值）、ready$（加载完成事件）与 changed$（变更事件）。

1. 默认值的多层合并。 各插件通过继承 ConfigProvider（定义见 tabby-core/src/api/configProvider.ts）提供 defaults 与按平台区分的 platformDefaults。ConfigService.mergeDefaults() 的合并顺序是：先取 platformDefaults[configPlatform]，再叠加 platformDefaults[platform]，最后叠加通用 defaults；多个 Provider 之间用 configMergeByDefault 归并。而 tabby-core 自身也有按平台切分的默认配置文件：configDefaults.yaml 之外还有 configDefaults.linux.yaml、configDefaults.macos.yaml、configDefaults.windows.yaml、configDefaults.web.yaml 四个平台变体，同目录均可见于 tabby-core/src/。

2. ConfigProxy：默认值不落盘。 加载时 store 被包装成一个 ConfigProxy（config.service.ts）：读属性时，用户配置里没有的值实时回退到 defaults 的深克隆；写属性时，若新值与默认值 deepEqual，则直接从真实 store 中 delete 该键。配合保存前的 __cleanup()，最终写入 YAML 文件的只包含"用户真正改过的值"，配置文件因此保持精简。

3. 版本化迁移与加密。 load() 用 js-yaml 解析文件内容，然后进入 migrate()：从源码结构看，迁移链已推进到 version 8（见 config.service.ts），历史迁移包括把 ssh.connections.privateKey 改为 privateKeys 数组、把终端/SSH/串口连接统一迁移到 profiles 数组、把字符串组名升级为带 id 的 groups 等。若配置带有 encrypted 标记，maybeDecryptConfig() 会循环向 VaultService 索取口令解密，解密失败时通过 platform.showMessageBox 给出"重试/清除配置/退出"选项；save() 则对称地调用 maybeEncryptConfig()。整个保存链路经 serializeFunction 串行化，避免并发写盘。

4. 插件黑名单过滤。 enabledServices() 会扫描 window['pluginModules'] 中各插件模块注入的 Provider 类，过滤掉 store.pluginBlacklist 或 store.providerBlacklist 中列出的插件/Provider，供各服务在取多播（multi: true）注入的 Provider 列表时安全地"按需剔除"。此外，readRaw()/writeRaw() 暴露了直接读写 YAML 字符串的通道，requestRestart() 则用于标记"需要重启应用才能生效"的变更。

四、快捷键：HotkeyProvider 与 HotkeysService

快捷键扩展点定义在 tabby-core/src/api/hotkeyProvider.ts：

export interface HotkeyDescription {
    id: string
    name: string
}

export interface Hotkey {
    strokes: string[] | string // may be a sequence of strokes
    isDuplicate: boolean
}

export abstract class HotkeyProvider {
    abstract provide (): Promise<HotkeyDescription[]>
}

注释里给出了一条硬性约束：提供 HotkeyProvider 的插件必须同时提供一个 ConfigProvider，在 hotkeys.foo 配置项中给出默认键位。核心模块自身通过 tabby-core/src/hotkeys.ts 导出的 AppHotkeyProvider 注册到 multi: true 的 HotkeyProvider 多播中。

主模块（tabby-core/src/index.ts）在构造器中订阅 hotkeys.hotkey$ 并处理了一批特殊前缀，这从源码结构看构成了一套"动态快捷键命名空间"约定：

• profile.<id>：按配置的快捷键名匹配 profile，命中则 profilesService.openNewTabForProfile(profile)；
• profile-selectors.<id> / group-selectors.<id>：弹出对应 Provider 或分组下的 profile 选择器（SelectorService）；
• command-selector / profile-selector：分别打开命令选择器、执行 core:profile-selector 命令。

也就是说，插件只要按 profile.xxx 这类规则注册快捷键，就能被主应用解释为"打开某个配置/选择器"，而无需主应用感知插件的存在。

五、标签恢复：TabRecoveryProvider 与恢复令牌

"tab recovery" 的扩展点定义在 tabby-core/src/api/tabRecovery.ts。插件继承 TabRecoveryProvider<T> 后需实现两个方法：

• applicableTo(recoveryToken): Promise<boolean>——判断给定的恢复令牌是否属于自己能恢复的标签类型；
• recover(recoveryToken): Promise<NewTabParameters<T>>——把令牌还原成开标签所需的参数描述，无法处理时返回 null。

RecoveryToken 至少含 type 字段（另可选 tabIcon、tabColor、tabPinned），文档中推荐的令牌格式为 { type: 'my-tab-type', foo: 'bar' } 这样的 JSON。Tabby 启动或重开标签时，会把已保存的令牌依次交给所有注册的 Provider，找到第一个 applicableTo 为真的那个执行恢复。

保存节奏在 AppService 构造器中（app.service.ts）：任何标签变化都会触发 recoveryStateChangedHint，另有 30 秒一次的定时兜底，经 debounceTime(1000) 后调用 tabRecovery.saveTabs(this.tabs)。启动时若配置 recoverTabs 为真，主窗口会从 recoverTabs() 拿回令牌列表逐个 openNewTabRaw。注意一个细节：即使 recoverTabs 关闭，tabRecovery.enabled 仍被设为 true 继续落盘，注释写明是为了"当前设置关闭时依然保留标签数据"，用户之后打开开关即可恢复。

六、日志与主题

日志。 tabby-core 从 tabby-core/src/api/index.ts 导出 Logger、ConsoleLogger 与 LogService（实现位于 tabby-core/src/services/log.service.ts），插件可注入日志服务并替换具体 Logger 实现（例如桌面版在 tabby-electron/src/services/log.service.ts 中提供了落盘实现），统一抽象则在 core 内。

主题。 主题扩展点定义在 tabby-core/src/api/theme.ts：

export abstract class Theme {
    name: string
    /** Complete CSS stylesheet */
    css: string
    terminalBackground: string
    macOSWindowButtonsInsetX?: number
    macOSWindowButtonsInsetY?: number
    followsColorScheme?: boolean
}

一个主题就是一整份 CSS 字符串加终端背景色，followsColorScheme 可声明跟随系统深浅色模式，macOS 下还能微调窗口按钮内嵌位置。core 自身以 NewTheme（tabby-core/src/theme.ts）注册进 Theme 多播。与之配套的是终端 16 色方案接口 TerminalColorScheme（foreground/background/cursor/colors 数组，可选 selection 与 cursorAccent），由 ThemesService 管理，终端插件据此渲染。

七、插件如何消费与导出 tabby-core：README 的完整用法

README 的后两段是面向插件开发者的操作规范，这里完整给出并对照源码验证。

1. 导入 API。 所有 public API 都从 tabby-core 包名根部导出：

import { AppService, TabContextMenuItemProvider } from 'tabby-core'

导出的全集以 tabby-core/src/index.ts 的 export * from './api' 为准，而 tabby-core/src/api/index.ts 又聚合了组件基类（BaseComponent、BaseTabComponent、SplitTabComponent）、各 API 抽象（ToolbarButtonProvider、ConfigProvider、HotkeyProvider、Theme、TabContextMenuItemProvider、CLIHandler、PlatformService、ProfileProvider 等）以及全部服务（AppService、ConfigService、HotkeysService、TabsService、TabRecoveryService、VaultService、LogService 等）。BaseTabComponent 是自定义标签组件的基类，配合 TabsService 的 NewTabParameters 即可接入标签体系。

2. 用 multi: true 导出自己的子类。 README 给出的模板：

@NgModule({
  ...
  providers: [
    ...
    { provide: TabContextMenuItemProvider, useClass: MyContextMenu, multi: true },
    ...
  ]
})

multi: true 是 Tabby 插件体系的通用约定：同一抽象类可以被多个插件各注册一个实现，消费方一次性注入数组。core 自己的 src/index.ts 就是活例证——PROVIDERS 数组里同时注册了 HotkeyProvider、Theme、ConfigProvider、TabContextMenuItemProvider（4 个上下文菜单实现）、TabRecoveryProvider、CLIHandler、FileProvider、ProfileProvider、CommandProvider，全部 multi: true，并通过 AppModule.forRoot() 以 ModuleWithProviders 的形式交给宿主应用。

另外两个 README 未展开但源码可见的细节：模块的引导组件是 AppRootComponent（index.ts 末尾 export { AppRootComponent as bootstrap }），以及文件末尾保留了 ToolbarButton as IToolbarButton、HotkeyDescription as IHotkeyDescription 等弃用别名导出，说明老版本 I 前缀接口命名已被接口直导出替代——升级插件代码时可留意。

小结：tabby-core 提供的能力与扩展点对照

README 声明的能力	核心服务/组件	插件扩展点（抽象类）	源码位置
tabbed interface services	AppService、TabsService	BaseTabComponent	services/app.service.ts
toolbar UI	工具栏组件	ToolbarButtonProvider	api/toolbarButtonProvider.ts
config file management	ConfigService、ConfigProxy	ConfigProvider	services/config.service.ts
hotkeys	HotkeysService、AppHotkeyProvider	HotkeyProvider	api/hotkeyProvider.ts
tab recovery	TabRecoveryService	TabRecoveryProvider	api/tabRecovery.ts
logging	LogService、Logger、ConsoleLogger	注入 Logger	services/log.service.ts
theming	ThemesService、NewTheme	Theme、TerminalColorScheme	api/theme.ts

tabby-core 的价值在于：它既是 Tabby 桌面/Web 双形态共用的运行时内核（标签、配置、快捷键、恢复、日志、主题全部抽象为可多播注入的服务），又是所有第三方插件的 API 供给方——任何新插件只需依赖 tabby-core 包、按 README 的 multi: true 约定导出子类，就能接入这套体系。