Windows Terminal 分屏焦点导航设计解析：moveFocus 与 focusPane 动作的完整决策链（2871）

Windows Terminal 的分屏（pane）最初只支持"方向式"焦点移动——用户可以用 moveFocus 往上下左右挪动焦点，但无法直接跳到某个指定分屏，也无法按"最近使用（MRU）"顺序切回上一个分屏。本文基于仓库中的设计规格 Focus Pane Actions（#2871 Pane Navigation），完整还原这个功能从用户诉求、六个候选方案（Proposal A–F）到最终落地的设计推理，并结合 src/cascadia 下的实际源码，说明 moveFocus(direction="prev") 与 focusPane(target=id) 两个动作是如何在设置解析、命令行参数处理和动作分发链路中实现的。读完后你将理解：Terminal 如何统一 keybinding、命令行 --action 与 Settings UI 三种入口的动作模型，以及"为什么最终只加了一个枚举值"这一兼容性的设计取舍。

背景：为什么方向式导航不够用

规格文档的起点是一个明确的现状描述：当时 Terminal 只能通过方向参数在分屏之间移动焦点。具体来说，moveFocus 动作只接受一个 direction 参数；而标签页（tab）层面已有 nextTab / prevTab 可以按顺序或按 MRU 顺序切换，并可通过 tabSwitcherMode 控制是否弹出"标签切换器"界面。分屏层面则完全没有对等的 MRU 或"直达"能力。

设计灵感直接来自 tmux 的 select-pane 命令（规格文档引用了 man tmux 原文）：

select-pane [-DLlMRU] [-T title] [-t target-pane]

     Make pane target-pane the active pane in window target-window, or set its
     style (with -P).  If one of -D, -L, -R, or -U is used, respectively the
     pane below, to the left, to the right, or above the target pane is used.
     -l is the same as using the last-pane command.

     -m and -M are used to set and clear the marked pane.  There is one marked
     pane at a time, setting a new marked pane clears the last.  The marked pane
     is the default target for -s to join-pane, swap-pane and swap-window.

tmux 在一条命令里同时支持"按编号直达"（-t target-pane）与"相对方向跳转"（-D/-L/-R/-U）两种语义，这正是该规格试图借鉴的目标形态。

三个驱动设计的目标场景

规格文档给出了三条用户故事（User Stories），它们是后续所有方案取舍的评判标准：

场景	诉求	关联 issue
场景 1	想通过命令行把窗口一次性拆成 4 个均等四角。当时做不到：启动动作执行期间用户无法移动焦点，split-pane 动作永远分割"当前"那个 pane，无法把焦点先挪开再分	#5464
场景 2	想快速切回"上一次操作过的分屏"（上一 pane 焦点）	#2871
场景 3	想绑定 alt+1、alt+2 之类的键位，直接聚焦 tab 内第 1、第 2 个分屏	#5803

值得注意的是规格文档专门讨论过的一个反直觉结论："用 pane switcher 配合 focusPane(target=id)"这种组合没有意义——既然用户已经知道要跳到哪个 pane，就没必要再弹出一个临时 UI 挡在前面；同理，方向式移动焦点时弹出切换器也是混乱的。这直接影响了最终方案对"切换器 UX"的态度（见"最终决议"一节）。

六个候选方案的完整推演（Proposal A–F）

这是整篇规格的核心：作者依次评估了六种动作（action）设计，并逐条列出利弊。理解这段推演过程，比记住结论更有价值，因为其中暴露的设计权衡（条件参数、枚举污染、MRU 语义歧义）对任何动作系统设计都有参考意义。

Proposal A：给 moveFocus 加 next / prev

moveFocus(direction="up|down|left|right|next|prev")

• 优点：确实能让"MRU 分屏切换"跑起来。
• 缺点：没有覆盖其他场景；MRU 切换在没有 UI 记录/展示 MRU 栈的前提下几乎不可用——因为"切换到 MRU pane"这个动作本身就会更新 MRU 栈，所以这种设计实际只允许用户跳回"最近用过的那个"或按最久未用顺序遍历。

规格文档标记：❌ 不再考虑。

Proposal B：focusNextPane / focusPrevPane，带 order 与 useSwitcher 参数

该方案来自实现 PR 中的讨论，原始 JSON 示例如下：

// Focus pane 1
// - This is sensible, no arguments here
{ "command": { "action": "focusPane", "id": 1 } },

// Focus the next MRU pane
// - Without the switcher, this can only go one pane deep in the MRU stack
// - presumably once there's a pane switcher, it would default to enabled?
{ "command": { "action": "focusNextPane", "order": "mru" } },

// Focus the prev inOrder pane
// - this seems straightforward
{ "command": { "action": "focusPrevPane", "order": "inOrder" } },

// Focus the next pane, in mru order, explicitly disable the switcher
// - The user opted in to only being able to MRU switch one deep. That's fine, that's what they want.
{ "command": { "action": "focusNextPane", "order": "mru", "useSwitcher": false } },

// Focus the prev inOrder pane, explicitly with the switcher
// - Maybe they disabled the switcher globally, but what it on for this action?
{ "command": { "action": "focusPrevPane", "order": "inOrder", "useSwitcher": true } }

简化后是三个动作：

• focusPane(target=id)
• focusNextPane(order="inOrder|mru", useSwitcher=true|false)
• focusPrevPane(order="inOrder|mru", useSwitcher=true|false)

优点：一切显式化（包括是否使用 pane switcher），还顺带支持了按顺序切换。缺点：next 与 prev 在 MRU 语义上是同一件事（"下一个最近使用的 pane"和"上一个最近使用的 pane"其实是同一个），而且"按顺序遍历分屏"这个 UX 是否成立都存疑——没有用户提过这个需求。

规格文档在此处留了一条重要备注：从这一点起，团队放弃了对 MRU 双向（next/prev）的支持，统一用 "last" 表示"上一个 MRU pane"。

❌ 不再考虑。

Proposal C：单动作合并参数

moveFocus(target=id|"up|down|left|right|last")

• 优点：只有一个 target 参数，写法最简单，没有条件参数问题。
• 缺点：无法在 Settings UI 中表达——混合类型枚举对字号（font weight）这种"每个枚举值有独立整型映射"的场景没问题，但这里 id 与方向值在语义上完全不同。

❌ 不再考虑。

Proposal D：两个动作（最终被采纳）

focusPane(target=id)
moveFocus(direction="up|down|left|right|last")

• 优点：每个动作只做一件事，语义明确。
• 缺点：两个动作覆盖相似行为；并且会把 "Direction" 枚举拆成 MoveFocusDirection 和 ResizeDirection（因为 resizePane(last) 毫无意义）。
• 附带说明：这个方案对"切换器 UX"没有特殊处理——两个动作都不会唤起 pane switcher。

Proposal E：三个动作

focusPane(target=id)
moveFocus(direction="up|down|left|right")
focusLastPane(usePaneSwitcher=false|true)

设计上 focusLastPane 可以唤起 pane switcher UI，后续按键可以在其可见期间沿 MRU 栈继续跳转。优点是考虑了未来的切换器 UX；缺点是三个动作覆盖相似行为。

❌ 不再考虑。

Proposal F：一个动作通吃（"tmux 方案"）

focusPane(target=id, direction="up|down|left|right|last")

此前这种设计被回避，因为 focusPane(target=4, direction=down) 语义模糊：是聚焦 pane 4，还是向下移动焦点？tmux 的答案是两者都做（先定位 target，再应用方向）。该方案不唤起切换器，连 direction=last 也不唤起。

• 优点：冗余动作最少。
• 缺点：组合参数"target 先生效"的行为是否直觉？并且隐含假设未来还会有独立的"打开切换器（带某种排序）"动作。

规格文档在此还留下一段作者自述的反思备注：是否需要一个独立的"以展开 pane 的方式打开 tab switcher"动作？也许 pane 直接显示在 tab switcher 里就该是切换器自身行为的一部分。

❌ 不再考虑。

最终决议：Proposal D + 命名修正为 prev

规格文档的结论部分记录了团队的最终决定，包含两个要点：

1. 采纳 Proposal D：新增 focusPane(target=id)，并在既有 moveFocus 的 direction 枚举中追加一个取值。团队认为没有必要为唤起"pane switcher"额外增加任何配置——"pane switcher" 应当只是 [高级标签切换器（#1502）](https://gitcode.com/GitHub_Trending/term/terminal/blob/20588130d8ef2ba40eb56bdae88e04cce7fc5b5d/doc/specs/?utm_source=gitcode_repo_files#1564 - Settings UI/spec.md) 功能的一部分，而不是独立的东西。
2. 命名修正：新增的方向值确定为 prev 而非 last，为了一致性（"consistency's sake"）。这与 Proposal B 阶段"用 last 表示 previous MRU pane"的中间态不同，最终落地时统一到了 prev 这个词上。

也就是说，最终 API 面是：

动作	参数	行为	是否唤起切换器
focusPane	target（pane 的 id）	直接聚焦指定分屏	否
moveFocus	direction = "up" / "down" / "left" / "right"	方向式移动焦点（既有能力）	否
moveFocus	direction = "prev"	切回上一个活动的分屏（tab 内 MRU）	否

源码印证：动作模型中的落地形态

规格中的这两个动作在当前代码库中都有对应的实现位置，可以逐一对应：

• 动作键名注册在 ActionAndArgs.cpp，其中 static constexpr std::string_view MoveFocusKey{ "moveFocus" } 与 static constexpr std::string_view FocusPaneKey{ "focusPane" } 正是规格中约定的两个动作名，证明实现严格沿用了 Proposal D 的命名（没有留下 focusLastPane、focusNextPane 等被淘汰方案的痕迹）。
• ActionArgs.h 中定义了 FocusPaneArgs（ACTION_ARGS_STRUCT(FocusPaneArgs, FOCUS_PANE_ARGS) 及 BASIC_FACTORY(FocusPaneArgs) 工厂），即 target=id 参数的 WinRT 动作参数结构；moveFocus 的参数结构则复用 direction 枚举。
• 动作分发在 AppActionHandlers.cpp 中完成：FocusDirection() == FocusDirection::None 的分支处理方向式焦点移动，而 focusPane 命令的处理处有一条值得注意的注释："There's currently no way for an inactive tab to be the sender of a focusPane command."——这从实现侧印证了 focusPane 是作用于"当前 tab 内的 pane"的 tab 内导航动作，与规格"在单个 tab 内切回上一个活动 pane"的 UX 定位一致。
• 命令行侧，AppCommandlineArgs.cpp 支持把 moveFocus / focusPane 作为启动动作（--action）参数解析，这正是"场景 1"的解法：启动命令行里可以插入焦点移动/聚焦动作，从而配合 split-pane 构造任意分屏树（比如 4 均等四角）。
• 实际焦点切换的容器逻辑位于 Tab.cpp 与 Pane.cpp，tab 内部维护 MRU 顺序，moveFocus(prev) 本质上是取 MRU 栈中上一个 pane 并请求其获得焦点。
• 对应的本地测试在 TabTests.cpp 与 CommandlineTest.cpp 中覆盖了 tab/pane 的焦点切换与命令行动作解析路径。

从源码结构看，MoveFocusDirection（含新增取值）与 ResizeDirection 被拆成两个枚举，恰好呼应了 Proposal D 缺点里预言的"枚举分叉"——resizePane 只有四个方向，moveFocus 多了一个 prev。

UI/UX 设计与兼容性论证

规格文档的 UI/UX 一节很短但关键：该设计唯一新增的 UX，就是允许用户通过一个动作移动到"单个 tab 内上一个活动的 pane"；规格本身不规定任何额外 UX（包括 pane switcher）。

"潜在问题（Potential Issues）"部分针对兼容性给出了明确论证，这也是该方案被选中的重要原因：

• 只是给一个既有枚举追加了一个枚举值，没有改动任何既有取值的含义；
• moveFocus 动作的 direction 默认值没有变化；
• moveFocus 没有新增任何参数，不存在"新参数改变既有语义"的风险。

对于存量配置和用户键位，这意味着 moveFocus 旧配置（例如绑定到方向键）的行为完全不变，新值 prev 只有显式使用才生效。

已知限制：无法"按序遍历"所有 pane

规格诚实地记录了一个遗留限制：在当前设计下，没有单一键位能在所有 pane 之间按序遍历。例如用户想把 Alt+] 绑成"下一个 pane"、Alt+ 绑成"上一个 pane"——这种移动只能是基于 MRU 的，因为"多步 MRU"并不存在；而按序（in-order）遍历能力从未被提出。规格认为这个限制可以接受，理由是"没人真正要求过按序遍历"。同时规格还留了一条后手：如果未来真需要 in-order 遍历，也许应该让 last 表示"上一个 MRU pane"，而把 next/prev 保留给按序遍历——但落地实现选择了直接命名 prev，把"按序遍历"的语义空间让给了未来。

延伸：与动作/键位体系的衔接

这个规格不是孤立存在的，它嵌在 Windows Terminal 更大的"统一动作模型"里：

• [统一键位与命令、合成动作名规格（#2046） 定义了 keybinding、Settings UI 与命令行共用同一套动作名（如 moveFocus、focusPane）的机制，#2871 的两个动作正是通过这套机制同时出现在三种入口中；
• Action IDs（#6899） 规定了动作 ID 的注册与文档化方式；
• 分屏本身的树状结构与 split-pane 动作由 Panes and Split Windows（#532） 定义，focusPane 的 target 即指向那棵树中的叶子节点；
• 按键绑定与动作参数的整体约定见 Keybindings-spec。

小结

#2871 这篇规格的价值在于它完整展示了"一个看似很小的功能（切回上一个分屏）如何逼出一整套动作系统的设计推演"：六个候选方案逐一对照三个用户场景，围绕"条件参数是否合法""MRU 语义是否自洽""枚举会不会被污染""Settings UI 能否表达"四个维度收敛，最终以最克制的方式落地——一个既有枚举加一个取值（prev），外加一个独立的新动作（focusPane）。当前仓库中 TerminalSettingsModel 与 TerminalApp 下的源码与测试，恰好保留了与规格一一对应的命名与结构，是理解 Windows Terminal 动作系统设计思想的绝佳一手材料。