Windows Terminal 广播输入设计规格：toggleBroadcastInput 的三种状态模型与源码落地

2026-09-06 13:13:38作者：温艾琴Wonderful

本篇技术指南基于 Windows Terminal 仓库中的规格文档（issue #2634），系统讲解"广播输入"（Broadcast Input）功能的设计动机、iTerm2 式模态广播与广播集（Broadcast Set）等三种状态模型、统一的 toggleBroadcastInput 动作定义，以及 UI 指示器方案。读完本文，你将掌握该功能的完整设计决策链，并能结合仓库当前源码理解 tab scope 的实现方式（Tab::ToggleBroadcastInput、Pane::BroadcastKey/Char/String 等），为后续绑定快捷键、定制主题边框颜色或扩展新 scope 提供依据。

![Windows Terminal 广播输入功能中，使用边框颜色标示正在接收广播输入的各个窗格](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/drafts/?utm_source=gitcode_repo_files#2634 - Broadcast Input/broadcast-input-borders.gif)

![广播输入在标签页上使用的 Segoe UI 风格网络塔图标](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/drafts/?utm_source=gitcode_repo_files#2634 - Broadcast Input/broadcast-segoe-icon.png)

一、功能定义与用户故事

"广播输入"是许多终端（iTerm2、SecureCRT、Terminator 等）中的常见功能：允许用户把同一份键盘输入同时发送到多个标签页或窗格（pane）。典型场景是在多个目录、多台服务器上同时执行相同的命令，省去了逐一切换窗格手工敲键的过程。

规格文档（[原始规格](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/drafts/?utm_source=gitcode_repo_files#2634 - Broadcast Input/#2634 - Broadcast Input.md)）明确了 iTerm2 所支持的四种用户故事，它们是整个设计的需求基础：

故事	行为
Story A	Send input to current session only：只把输入发送到当前会话（默认设置）
Story B	Broadcast to all panes in all tabs：键入的任何内容发送到本窗口的所有会话
Story C	Broadcast to all panes in current tab：键入的内容发送到当前标签页的所有窗格
Story D	Toggle broadcast input to current session：切换本会话是否接收窗口内的广播按键

设计参考与取舍

规格文档指出，该设计主要受 iTerm2 的广播输入实现启发（仓库 issue #2634 中曾有对 iTerm2 工作机制的细致拆解）。同时考察过另外两种方案并放弃：

SecureCRT：通过一个"聊天窗口"把其中输入的内容发到所有标签页。规格作者认为这种交互不符合人体工学，未认真考虑。
Terminator（*nix）：通过"分组"（groups）把窗格划入组内，然后选择向所有窗格、某个组或不广播。规格作者认为这比 iTerm2 式方案表达力弱，因此也仅作为后续"广播组"演进的参考。

二、Proposal 1：iTerm2 式模态广播

iTerm2 把广播输入实现为一套"模态"系统，用户在以下模式之一中切换：

广播到所有标签页的所有窗格
广播到当前标签页的所有窗格
广播到当前标签页内的某一组窗格
完全不广播（默认行为）

这些模式具有按标签页的状态（per-tab state）特征：存在一个全局的"广播到所有标签与窗格"属性；此外每个标签页又有一对值——

是否把输入发送到本标签页的所有窗格？
若不是，则发送到哪些窗格？

一个关键约束是：不启用全局"广播到所有人"模式时，无法把输入发到标签页 A 的某个窗格和标签页 B 的另一个窗格。

这套模型可以拆解为以下四个动作（JSON 形式，可直接出现在用户设置的 keybindings 中）：

{ "action": "toggleBroadcastInput", "scope": "window" },
{ "action": "toggleBroadcastInput", "scope": "tab" },
{ "action": "toggleBroadcastInput", "scope": "pane" },
{ "action": "disableBroadcastInput" },

配套的内部属性包括：

窗口级（TerminalPage 层）属性 broadcastToAllPanesAndTabs
每标签页属性 broadcastToAllPanes
每标签页的"广播目标窗格集合"

各 scope 的语义如下：

"scope": "window"：切换窗口的"广播到所有标签与窗格"设置。
"scope": "tab"：切换标签页的"广播到本标签所有窗格"设置。注意它不修改用户在本标签页中广播目标窗格的集合——若用户此前已指定了窗格集合，反复开/关该设置后会恢复到该集合。
"scope": "pane"：把当前窗格加入本标签页的广播目标集合。规格中留下了待讨论点：它是否应顺带关闭标签页的 broadcastToAllPanes 设置，还是互不影响。
"disableBroadcastInput"：针对当前标签页，把全局设置、标签页设置都置为 false，并清空广播目标窗格集合。规格中另一条待定思路是把它等价于 "action": "toggleBroadcastInput", "scope": "none"。

优点：

与 iTerm2 完全一致，有充分先例。
未开启全局广播时，输入只会到达当前标签页（内）的部分窗格；只有全局广播模式下才需要担心输入发送到非活动标签页。
可以为第一个标签页维护一套广播窗格集合，再为第二个标签页维护另一套，互不影响。

缺点：

tab 与 pane 的交互略显怪异。例如：为标签 1 开启广播 → 切换到标签 2 → 为标签 2 的某个窗格开启广播。此时有两种合理解释：① 输入同时到达标签 1 的全部窗格和标签 2 的那个窗格；② 输入只到达标签 2 的那个窗格。用户容易产生困惑。
无法在非活动标签页中广播给部分窗格的同时再广播给活动标签页的窗格——所有目标窗格都必须位于活动标签页内。
遗留问题：当一个正在被广播的窗格被再次分屏（split）时，新产生的窗格是否自动加入广播集合？

对原型 PR 的影响：原型 PR #9222 实际上只实现了 { "action": "toggleBroadcastInput", "scope": "tab" }。若把 tab 定为未指定 scope 时的默认值，该 PR 几乎不需要修改即可合入；未来 PR 再为 toggleBroadcastInput 增加更多参数，也不会破坏已经为这个动作绑定了快捷键的用户。

三、Proposal 2：统一的广播集（Broadcast Set）

这是规格作者调研 iTerm2 之前的原始设计。核心是一个窗格集合（broadcast set）：集合内的所有窗格在收到活动窗格的 KeySent / CharSent 事件之外，也会收到同样的广播事件（活动窗格本身可以是集合的一员）。若集合中某窗格处于只读状态，则不处理广播事件。

对应四个用户故事的集合操作语义：

A 只发送到活动窗格：把全部窗格移出广播集。
B 发送到所有标签页的所有窗格：若集合已包含全部窗格则全部移除；否则把全部窗格加入集合。
C 发送到当前标签页的所有窗格：若当前标签页的窗格全部在集合中则全部移除；否则把它们全部加入集合。
D 切换当前窗格：在集合中则移除，否则加入。

动作定义与 Proposal 1 完全相同：

{ "action": "disableBroadcastInput" },
{ "action": "toggleBroadcastInput", "scope": "window" },
{ "action": "toggleBroadcastInput", "scope": "tab" },
{ "action": "toggleBroadcastInput", "scope": "pane" },

内部属性只有一个：窗口级（TerminalPage 层）的广播目标窗格集合。

优点：

心智模型简单：要么把窗格加入广播集，要么移出。
可以广播到多个标签页中的部分窗格，而不必广播到"所有标签的所有窗格"。

缺点：

与 iTerm2 略有差异。
同样存在"新分屏的窗格是否自动入集合"的问题。
无法在每个标签页维护各自独立的广播集合。规格文档给出了一段具体演示：
1. 在标签 1 把窗格 A、B 加入广播集，在 A 或 B 中打字会同时到达两者；
2. 在标签 1 切到窗格 C，输入会到达 A、B、C；
3. 在标签 1 切到窗格 D，输入到达 A、B、D；
4. 切到标签 2 的窗格 E，输入到达 A、B、E。
也就是说无法形成"标签 1 里是 A+B，标签 2 里是 E+F"这样的两组广播；用户若要在两组之间来回打字，就得反复切换窗格集合。

对原型 PR 的影响：与 Proposal 1 相同，tab 作为 scope 的默认值先落地；未来支持其他 scope 时，把实现从"标签级属性"改为"广播窗格集合"。

四、Proposal 3：iTerm2 的"微调版"

Proposal 3 保留 Proposal 1 的按标签页状态，但用广播集合取代"广播到全部窗格"布尔开关：

"scope": "tab"：若本标签页的广播集已包含全部窗格则全部移除；否则把本标签页所有窗格加入该标签页的广播集。
"scope": "pane"：若当前窗格在本标签页的广播集中则移除，否则加入。

这样就没有"广播到本标签所有窗格"的独立标签级设置了，只依赖该标签页的广播集合来表达。

优点：

继承 Proposal 1 的全部优点；
消除了 Proposal 1 中在"本标签全部窗格"与"本标签部分窗格"之间来回切换的怪异行为。

缺点：

与 iTerm2 有轻微差异（作者强调"只是一点点"）；
同样无法跨非活动标签页广播到部分窗格；
新分屏窗格是否自动入集合的疑问仍在。

对原型 PR 的影响：与 Proposal 1 相同——原型 PR 不做修改即可合入；未来为其他 scope 补 PR 时，再把标签内广播的实现从"标签级属性"改为"窗格集合"。

五、关键决策点：三个提案共用同一组动作

规格文档的结论部分指出：作者当时并未在三个方案中做出最终决定（TODO: Make a decision），但幸运的是三个提案实际使用同一组动作定义，因此当下选择哪个并不关键——可以先用 PR #9222 落地 "scope": "tab" 的实现来解除阻塞，其余 scope 留待未来，长期方向再定夺。1 与 3 的最大优势是与先例最接近，2 则更容易向"广播组"扩展（见下文"未来扩展"）。

规格文档给出的实施计划（按顺序）：

恢复 PR #9222，用它实现 "scope": "tab"——无论最终选哪个提案，这一步的实现都相同，且对多数用户最重要。可以进一步建议 scope 的默认值就是 tab，这样初版甚至不需要支持任何参数。
为标签页右键菜单增加"切换广播输入"条目，并根据当前状态动态改变图标。
实现 "scope": "window"——同样与提案选择无关。
在 Proposal 2 与 3 之间做出长期决定。
实现 "scope": "pane"。

六、UI/UX 设计：如何让用户看见"正在广播"

规格文档明确这是"快速而脏"（quick & dirty）的规格，UI 部分从简，但给出了四条可落地的指示方案：

标签页图标：当某个窗格正在被广播到（broadcasted to）时，在其所属标签页上显示一个网络塔（Network Tower）的 Segoe UI 图标（即上文配图所示的图标）。若所有标签页都被广播到，则每个标签都显示该图标；若某非活动标签页中存在被广播到的窗格，也在其标签上显示图标。
窗格标题栏：在窗格标题栏（对应仓库 issue #4998）上同样显示该图标，从规格上下文看这是最合理的展示位置。
窗格边框配色：原型 PR 中建议过用某种"强调色"（accent color）变体来渲染正在接收广播输入的窗格边框。Windows Terminal 本就使用强调色作为活动窗格边框，而 SystemAccentColorLight* / SystemAccentColorDark* 可以提供相同色相、不同明度/饱和度的变体——这恰能表达"该窗格不是活动窗格，但会接收输入"。该颜色必须能像窗格边框色一样被用户主题覆盖。
背景条纹：iTerm2 会为所有被广播到的窗格绘制背景"条纹"。规格作者认为该方案与背景图像的叠加关系尚不明确，建议暂不实现，作为后续跟进项。

此外，规格文档还给出了标签页右键菜单（tab context menu）方案：参照 iTerm2 的菜单项形态，在 Windows Terminal 的标签右键菜单中以嵌套条目形式加入广播切换项，并应让 MenuItem 图标随当前广播状态动态变化。

七、实施计划与未来扩展

规格文档以 iTerm2 多年来积累的用户请求为参照，预判了 Windows Terminal 用户必然会提出的需求：

跨窗口广播（iTerm2 对应请求 #6709）：实现较直接，但需要与 Monarch（终端会话管理组件）协作，作者担心每个按键都跨进程边界传送带来的性能开销。动作形式大概是 { "action": "toggleBroadcastInput", "scope": "global" }。
"广播命令"（iTerm2 #6451、#5563）：不仅广播按键，还广播某些动作。例如 iTerm2 有一个可手动清空终端缓冲区的动作（Windows Terminal 侧对应 issue #1882）；"粘贴"广播到各窗格是合理的，"复制"则意义不大，"打开查找对话框/下一个匹配"之类动作也有可能。规格认为这大概需要单独一份规格来设计。
不同广播模式使用不同颜色（iTerm2 #6007）：global、tab、pane 三种 scope 各用一个颜色来区分，这与主题化（issue #3327）可以结合，形如 pane.broadcastBorderColor.globalScope、pane.broadcastBorderColor.paneScope 之类的属性（作者坦言"不太喜欢这些名字，但你能理解意思"）。
广播组（Broadcast groups）（iTerm2 #5639、#3372）：作者认为这是"最有意思的请求"，也点出了前述提案的最大短板——Proposal 2 只存在一个顶层广播组，Proposal 1 与 3 只有按标签页划分的广播组，都无法支持多个并存的广播组。组应跨标签页工作，这暗示 Proposal 2 更接近组的形态（多个顶层集合而非一个）。核心难点是：如何向用户区分不同的组？例如在标签页角落显示带编号的广播图标（如"📡: 1"）。一个窗格能否同时属于多个广播集？自然的参数设计是 { "action": "toggleBroadcastInput", "scope": "tab", "group": 1 }——把本标签全部窗格加入（或移出）广播组 1；若这些窗格原本在其他组，则移动到指定组；若本标签全部窗格都已在该组，则全部移除。该方案也对应 Terminator 的按组广播模式，但 UI 复杂度会迅速上升。
像素着色器路线：把窗格当前的广播状态暴露给像素着色器（pixel shader），用户即可用自定义着色器在文字后面绘制条纹——这是背景条纹需求的一种可能解法。

八、规格在仓库当前源码中的落地

规格文档写作时功能尚在原型阶段（PR #9222），但当前仓库源码显示 toggleBroadcastInput 动作及其 tab scope 实现已经合入，并且与规格的结论一致：先落地按标签页的状态，动作名保持稳定以便未来扩展 scope。下面逐层给出源码证据。

动作注册：settings 层的动作表

defaults.json 第 611 行将动作注册进默认设置的动作表：{ "command": "toggleBroadcastInput", "id": "Terminal.ToggleBroadcastInput" }。
ActionAndArgs.cpp 第 101 行定义了字符串常量 ToggleBroadcastInputKey{ "toggleBroadcastInput" }，即用户 JSON 中书写的动作名。
AllShortcutActions.h 第 112 行在 ON_ALL_ACTIONS 宏列表中登记 ToggleBroadcastInput，使其成为可被用户绑定快捷键的一等动作。
ActionMap.cpp 第 158 行把它映射到 ShortcutAction::ToggleBroadcastInput，并关联资源键 ToggleBroadcastInputCommandKey（各语言资源文件如 en-US/Resources.resw 中均有对应条目，供设置界面显示）。

动作分发：从 TerminalPage 到活动标签

AppActionHandlers.cpp 第 1540 行附近定义了分发入口 TerminalPage::_HandleToggleBroadcastInput，其核心逻辑仅一句：取当前活动标签并调用 activeTab->ToggleBroadcastInput()。这说明该动作的作用对象是当前活动标签页，与规格中"scope 缺省为 tab、首版不带参数"的决策吻合。

状态载体：按标签页的可观察属性

TerminalTabStatus.h 第 22 行定义了广播状态的载体：

WINRT_OBSERVABLE_PROPERTY(bool, IsInputBroadcastActive, PropertyChanged.raise);

这正是规格 Proposal 1/3 中"per-tab 属性"的源码实现：每个标签页持有一个 IsInputBroadcastActive 布尔状态，且作为 WinRT 可观察属性在变化时触发 PropertyChanged，从而驱动 UI 刷新。

标签页内实现：Tab::ToggleBroadcastInput

Tab.cpp 第 2205 行的 Tab::ToggleBroadcastInput() 完成三件事：

计算新状态 newIsBroadcasting = !IsInputBroadcastActive() 并写回 _tabStatus；
对根窗格调用 _rootPane->EnableBroadcast(newIsBroadcasting)；
开启时，为该标签页内已有窗格挂接广播事件处理器 _addBroadcastHandlers(control, events)（第 2244 行起）。

规格实施计划第 2 项"为新建窗格自动纳入广播"在源码中同样可见：Tab.cpp 第 671、787 行在创建/挂载窗格处执行 pane->EnableBroadcast(_tabStatus.IsInputBroadcastActive())，第 1223 行附近在为新窗格挂接事件时先判断 _tabStatus.IsInputBroadcastActive()。从源码结构看，新分屏产生的窗格在标签广播开启状态下会自动加入广播，这实际上回答了规格中"新 split 是否入集合"的悬而未决问题。

_addBroadcastHandlers 中（第 2244 行起）的回调逻辑是：当 IsInputBroadcastActive() 为真时，把源窗格的事件转发为 tab->_rootPane->BroadcastKey/BroadcastChar/BroadcastString(...)。

窗格树内转发：Pane::Broadcast*

Pane.cpp 第 2998 行的 EnableBroadcast(bool) 以递归方式遍历窗格树：叶窗格设置 _broadcastEnabled，同时把光标显示状态改为 CursorDisplayState::Shown（让被广播的窗格也显示光标，强化"这里也在接收输入"的视觉反馈），并调用 UpdateVisuals()；非叶窗格则向 _firstChild/_secondChild 递归。

三个广播入口（第 3018–3063 行）结构一致，均以 WalkTree 遍历整棵窗格树：

void Pane::BroadcastKey(const winrt::Microsoft::Terminal::Control::TermControl& sourceControl,
                        const WORD vkey,
                        const WORD scanCode,
                        const winrt::Microsoft::Terminal::Core::ControlKeyStates modifiers,
                        const bool keyDown)
{
    WalkTree(& {
        if (const auto& termControl{ pane->GetTerminalControl() })
        {
            if (termControl != sourceControl && !termControl.ReadOnly())
            {
                termControl.RawWriteKeyEvent(vkey, scanCode, modifiers, keyDown);
            }
        }
    });
}

其中 BroadcastChar 调用 termControl.RawWriteChar(character, scanCode, modifiers)，BroadcastString 调用 termControl.RawWriteString(text)。两个细节与规格完全对应：

排除源窗格（termControl != sourceControl）：源窗格自身已经处理了这次输入，无需自我重放；
跳过只读窗格（!termControl.ReadOnly()）：正是规格 Proposal 2 中"If a pane is read-only in the broadcast set, then it won't handle those broadcasted events (obviously)"的实现。

转发使用的 RawWrite* 系列接口把按键、字符、文本直接写入目标窗格的终端，与用户键盘路径汇合，因此广播窗格里的 shell 收到的输入与真实键入无法区分。

视觉指示：BroadcastPaneBorderColor 主题资源

规格 UI 部分"用强调色变体标示被广播窗格边框、且必须可被用户主题覆盖"的建议，在源码中落地为独立主题资源。Pane.cpp 第 3065 行的边框颜色计算逻辑为：

winrt::Windows::UI::Xaml::Media::SolidColorBrush Pane::_ComputeBorderColor()
{
    if (_lastActive)
    {
        return _themeResources.focusedBorderBrush;
    }

    if (_broadcastEnabled && (_IsLeaf() && !_content.ReadOnly()))
    {
        return _themeResources.broadcastBorderBrush;
    }

    return _themeResources.unfocusedBorderBrush;
}

即优先级为：活动窗格 > 被广播窗格 > 普通非活动窗格，且只读窗格不会被渲染成"被广播"样式。TerminalPage.cpp 第 5308 行通过主题资源键 BroadcastPaneBorderColor 解析该颜色，验证了它是可被用户主题覆盖的独立资源——正是规格所要求的"类似窗格边框色那样可覆盖"。

九、小结

这份规格的价值在于：它用一个刻意"轻量的"设计文档，把广播输入这件事拆成了两层——面向用户/面向设置的稳定动作契约（toggleBroadcastInput 的 window/tab/pane 三个 scope 加 disableBroadcastInput）与面向实现的自由状态模型（模态属性 vs 窗口级广播集 vs 按标签页广播集）。由于三个提案共用同一组动作，Windows Terminal 得以先以 tab scope 解除实现阻塞，把状态模型的长期选择延后。当前仓库源码证实了这一路线：Tab::ToggleBroadcastInput + 标签级 IsInputBroadcastActive 状态 + 窗格树 Broadcast* 转发 + BroadcastPaneBorderColor 主题资源，共同构成了规格中"scope: tab"提案的完整落地；而全局 scope、广播组、广播动作、着色器条纹等扩展方向，仍按规格的"Future Considerations"清单留待后续版本。