Windows Terminal VT52 兼容模式解析：DECANM 模式切换、状态机改造与键盘映射

本文基于 Windows Terminal（含 conhost）仓库中 doc/specs/#976 - VT52 escape sequences.md 设计文档展开，系统讲解如何把散落在 VT100 实现中的 VT52 命令剥离为独立的兼容模式：包括 DECANM 模式切换链路、StateMachine 状态机改造（含 VT52 特有的 Vt52Param 状态）、VT52 命令到现有 ITermDispatch 方法的复用映射、TerminalInput 的 VT52 键盘序列生成规则，以及图形模式字符集映射。读完本文后，你可以完整理解该功能的设计动机、在源码中的落地位置，以及各 VT52 转义序列与按键序列的准确对应关系。

一、问题背景：VT52 命令与 VT100 序列的冲突

设计文档开篇指出的核心问题是：VT52 的命令此前并没有实现为独立模式，而是直接混在 VT100 的解析路径中，因此会与 VT100 规范里定义在相同编码上的序列产生冲突。文档原文（VT52 escape sequences spec）描述：

The existing VT52 commands aren't currently implemented as a separate mode, so they conflict with sequences defined in the VT100 specification. This is blocking us from adding support for the VT100 Index (IND) escape sequence, which is one of the missing commands required to pass the test of cursor movements in Vttest.

典型冲突例子就是 ESC I：在 VT52 中它是 Reverse Line Feed，而在 VT100 中它是 Index（IND，光标下移一行）的一部分语义空间，两者无法同时无条件生效。这个冲突直接阻塞了 VT100 IND 序列的实现，而 IND 正是 Vttest 光标移动测试所要求的命令之一。

因此该 spec 的目标是：拆分并扩展 VT52 支持，让全部核心 VT52 命令都工作在一个显式的 VT52 模式下，从而与 ANSI/VT100 模式互不干扰。

二、总体设计：用 DECANM 引入独立的 VT52 模式

spec 的方案设计部分提出：引入对 DECANM 私有模式序列（CSI ? 61 h / CSI ? 61 l）的支持，用它从默认的 ANSI 模式切换到新的 VT52 模式；进入 VT52 模式后，由于 VT100 的 CSI 模式序列已不再生效，回退则由一个专门的 VT52 命令 Enter ANSI Mode（ESC <）完成。

也就是说，两种模式各有自己的“开关”：

方向	序列	形式
ANSI → VT52	CSI ? 61 l（DECANM reset）	VT100 CSI 私有模式
VT52 → ANSI	ESC <（Enter ANSI Mode）	VT52 单字母转义命令

在仓库当前实现中，这条链路已经完全落地，涉及四类组件，与 spec 的模块划分一一对应：

1. 状态机：src/terminal/parser/stateMachine.hpp / stateMachine.cpp——引入 Mode 标志与 Vt52Param 状态；
2. 分派引擎接口：IStateMachineEngine.hpp 新增 ActionVt52EscDispatch；
3. 输出引擎：OutputStateMachineEngine.cpp 实现 VT52 命令分派；
4. 适配器与输入：adaptDispatch.cpp 的 SetAnsiMode 与 terminalInput.cpp 的模式标志。

三、状态机改造：Mode 标志、Vt52Param 状态与 Vt52EscDispatch

3.1 Mode 标志：ANSI 与否的二元开关

spec 要求在 StateMachine 类中引入一个表示当前激活模式的标志。实现位于 stateMachine.hpp：

enum class Mode : size_t
{
    AcceptC1,
    Ansi,
};

void SetParserMode(const Mode mode, const bool enabled) noexcept;
bool GetParserMode(const Mode mode) const noexcept;

Mode::Ansi 为真时状态机按完整 VT100/ANSI 路径解析；为假时即处于 VT52 模式。注意 Mode::AcceptC1 是另一个独立标志——输入引擎（ConPTY 场景）必须始终接受 C1 控制码，这在 stateMachine.cpp 构造函数 中初始化。

3.2 Escape 状态的分流：VT52 模式下禁止 CSI/OSC/SS3 路径

spec 的关键论点是：VT52 模式下“不能出现 CSI、OSC、SS3 这些路径”。stateMachine.cpp 的 _EventEscape 正是按此实现的：收到 ESC 之后的第二个字符，若处于 ANSI 模式则依次尝试进入 CsiEntry（[）、OscParam（]）、Ss3Entry（O，仅输入引擎）、DcsEntry（P）、SosPmApcString（X/^/_）等状态；而 _parserMode.test(Mode::Ansi) 为假时，这些分支全部跳过，只剩两条出路：

else if (_isVt52CursorAddress(wch))   // 'Y'（0x59）
{
    _EnterVt52Param();
}
else
{
    _ActionVt52EscDispatch(wch);
    _EnterGround();
}

（见 stateMachine.cpp#L1125-L1161。）_isVt52CursorAddress 的判断在 stateMachine.cpp#L258-L261，只认 Y。

3.3 Vt52Param 状态：参数跟在命令字符之后

VT52 最特殊的一条命令是 Direct Cursor Address（ESC Y <row> <col>）：它的两个参数不是像 CSI 那样跟在命令字符前面，而是跟在命令字符之后，而且直接用 ASCII 字符表示（空格代表 1）。为此状态机新增了专用状态 VTStates::Vt52Param（stateMachine.hpp#L181）。

处理逻辑在 _EventVt52Param：每收到一个字符就压入 _parameters，收满 2 个字符后以固定命令符 'Y' 触发分派并回到 Ground：

_parameters.push_back(wch);
if (_parameters.size() == 2)
{
    // The command character is processed before the parameter values,
    // but it will always be 'Y', the Direct Cursor Address command.
    _ActionVt52EscDispatch(L'Y');
    _EnterGround();
}

这也解释了 spec 中的实现建议：既有的 ActionEscDispatch 不带参数，无法承载 DCAC，所以 IStateMachineEngine 接口新增了带参数列表的分派入口（IStateMachineEngine.hpp#L42）：

virtual bool ActionVt52EscDispatch(const VTID id, const VTParameters parameters) = 0;

状态机侧的对应动作 _ActionVt52EscDispatch 会把累积的 identifier（可含中间字符）与参数一并交给引擎。输出引擎与输入引擎各自实现该接口：输出引擎做真正分派（见下节），输入引擎则直接返回 true（InputStateMachineEngine.cpp#L372），因为 VT52 的接收序列只在输出解析路径上有意义。

四、VT52 命令集实现：对现有 VT100 能力的复用

spec 的核心判断是：大部分缺失的 VT52 功能可以用现有 VT100 方法表达。OutputStateMachineEngine::ActionVt52EscDispatch 的实现与 spec 清单逐条对应：

VT52 命令	序列	引擎中的分派（OutputStateMachineEngine.cpp#L342-L400）
Cursor Up	ESC A	CursorUp(1)
Cursor Down	ESC B	CursorDown(1)
Cursor Right	ESC C	CursorForward(1)
Cursor Left	ESC D	CursorBackward(1)
Enter Graphics Mode	ESC F	Designate94Charset(0, DecSpecialGraphics)
Exit Graphics Mode	ESC G	Designate94Charset(0, ASCII)
Cursor Home	ESC H	CursorPosition(1, 1)
Reverse Line Feed	ESC I	ReverseLineFeed()
Erase to End of Display	ESC J	EraseInDisplay(ToEnd)
Erase to End of Line	ESC K	EraseInLine(ToEnd)
Direct Cursor Address	ESC Y rc	CursorPosition(r - ' ' + 1, c - ' ' + 1)
Identify	ESC Z	Vt52DeviceAttributes()
Enter Keypad Mode	ESC =	SetKeypadMode(true)
Exit Keypad Mode	ESC >	SetKeypadMode(false)
Enter ANSI Mode	ESC <	SetMode(DECANM_AnsiMode)

几点实现细节值得注意：

• DCAC 的取值换算：两个参数是原始 ASCII 字符，引擎里用 value() - ' ' + 1 换算成 1 起始的行/列（' '→1）。spec 同时指出了 DCAC 与 CUP（CSI H）在边界处理上的理论差异：CUP 会把越界坐标钳制（clamp），而 DCAC 对越界坐标是“逐个独立忽略”（行越界忽略行、列越界仍可解释）；spec 作者认为“没几家做对，所以问题不大”，实现上直接复用了 CursorPosition。
• Identify 响应：ESC Z 触发的 Vt52DeviceAttributes 返回 ESC / Z。注释写得很清楚：真正的 VT52 终端通常用 ESC / K 自报家门，但模拟 VT52 的终端应当返回 ESC / Z——这与 spec 的要求一致。
• 模式命令复用：ESC = / ESC > 落到 SetKeypadMode，即 DECKPAM/DECKPNM 的通用处理（adaptDispatch.cpp#L2054-L2060），它只改 TerminalInput 的 Keypad 输入模式标志；而 ESC < 走 SetMode(DECANM_AnsiMode)，与 CSI 路径汇合（见下节）。
• 打印命令明确不在范围内：spec 列举了 VT52 的 Auto Print（ESC ^/ESC _）、Print Controller（ESC W/ESC X）、Print Cursor Line（ESC V）、Print Screen（ESC ]）四条打印命令，但认为它们并非核心命令集，且项目连 VT102 的打印命令都尚未支持，故列为 out of scope。当前引擎的 switch 中也不存在这些分支。
• 关于 ESC ? x 这类带中间字符的序列（VT52 模式下的 DECKPAM 小键盘键，见第六节）：? 落在中间字符区间（0x20–0x2F），状态机进入 EscapeIntermediate 并经由 _ActionCollect 把中间字符并入 VTIDBuilder（stateMachine.cpp#L487-L493），因此最终 identifier 是多字符的，可与简单的 ESC x 区分开。

五、模式切换的完整调用链

spec 的 “Changing Modes” 一节给出的实现路径，在仓库中逐环节可见：

1. ANSI → VT52（DECANM）：CSI 私有模式参数经 AdaptDispatch::_ModeParamsHelper 路由，其中 DECANM_AnsiMode 分支直接 return SetAnsiMode(enable)（adaptDispatch.cpp#L1782-L1783）；
2. SetAnsiMode 的核心动作（adaptDispatch.cpp#L2062-L2076）：

void AdaptDispatch::SetAnsiMode(const bool ansiMode)
{
    // When an attempt is made to update the mode, the designated character sets
    // need to be reset to defaults, even if the mode doesn't actually change.
    _termOutput.SoftReset();

    _api.GetStateMachine().SetParserMode(StateMachine::Mode::Ansi, ansiMode);
    _terminalInput.SetInputMode(TerminalInput::Mode::Ansi, ansiMode);

    // While input mode changes are often forwarded over conpty, we never want
    // to do that for the DECANM mode.
}

三件事：SoftReset 重置被指定的字符集（无论模式是否真的变化）；把 Mode::Ansi 写入状态机的 parser mode；把 TerminalInput::Mode::Ansi 写入输入实例。注释还特别强调：DECANM 引起的输入模式变化永远不会转发过 ConPTY，避免宿主终端与应用互相干扰。 3. VT52 → ANSI（ESC <）：由 VT52 分派路径回到 SetMode(DECANM_AnsiMode)（OutputStateMachineEngine.cpp#L390-L392），与 spec“在 OutputStateMachineEngine 中与其他 VT52 命令同地处理，最终等价于设置 DECANM”的描述一致。 4. 状态可查询：RequestMode（DECRQM）对 DECANM 的查询会读取状态机当前的 parser mode 并上报（adaptDispatch.cpp#L1957-L1959），即 DECANM 的状态源是 StateMachine::GetParserMode(Mode::Ansi)，而不是一个独立布尔位——从源码结构看，这保证了 CSI 查询结果与解析行为永远一致。

spec 还顺带提醒：当时 ANSI 模式下 DECKPAM（应用小键盘模式）尚未实现，可能需要先补齐。就当前仓库而言，SetKeypadMode 已存在并被 DECNKM_NumericKeypadMode（CSI ? 66 h/l）与 VT52 的 ESC =/ESC > 共用（adaptDispatch.cpp#L2057-L2060），该前置条件已经满足。

六、VT52 键盘输入：TerminalInput 的按键序列映射

spec 指出，VT52 模式下功能键、光标键、小键盘产生的转义序列与 ANSI 模式不同，因此 TerminalInput 类需要保留当前模式标志并按模式生成序列（实现中即 TerminalInput::Mode::Ansi，由上文 SetAnsiMode 设置）。由于 VT52 键盘与 PC 键盘并非一一对应，spec 的取舍原则是：拿不准时以 XTerm 的默认映射为准。以下映射表完整继承自 spec（基于 XTerm 默认映射）。

6.1 功能键

F1–F4 生成简单的 ESC 前缀（对应 VT100 小键盘上的四个功能键），VT52 模式下不受修饰键影响：

键	ANSI 模式	VT52 模式
F1	SS3 P	ESC P
F2	SS3 Q	ESC Q
F3	SS3 R	ESC R
F4	SS3 S	ESC S

F5–F12 及 Menu 键生成与 ANSI 模式相同的序列，只是不受修饰键影响（对应 VT220 顶排功能键的子集，Windows 的 Menu 键映射到 VT220 的 DO 键）：

键	序列
F5	CSI 1 5 ~
F6	CSI 1 7 ~
F7	CSI 1 8 ~
F8	CSI 1 9 ~
F9	CSI 2 0 ~
F10	CSI 2 1 ~
F11	CSI 2 3 ~
F12	CSI 2 4 ~
Menu	CSI 2 9 ~

6.2 光标键与编辑键

光标键在 VT52 模式下降级为简单 ESC 前缀（对应 VT100 的光标键；Home/End 属于 XTerm 扩展）。在 VT52 模式下，它们既不受修饰键影响，也不受 DECCKM（Cursor Keys 模式）影响：

键	ANSI 模式	VT52 模式
Up	CSI A	ESC A
Down	CSI B	ESC B
Right	CSI C	ESC C
Left	CSI D	ESC D
End	CSI F	ESC F
Home	CSI H	ESC H

编辑键生成与 ANSI 模式相同的序列，只是不受修饰键影响（对应 VT220 编辑键子集）：

键	序列
Ins	CSI 2 ~
Del	CSI 3 ~
PgUp	CSI 5 ~
PgDn	CSI 6 ~

6.3 数字小键盘

Num Lock 关闭时，小键盘大部分键等价于光标键/编辑键，另加中央 5 键。VT52 模式下大部分修饰键被忽略，只有 Shift 有特殊含义：它等价于开启 Num Lock（即键位只产生对应数字字符或 .）；反过来 Num Lock 开启时默认产生数字，按 Shift 才进入光标/编辑功能。

键	别名	ANSI 模式	VT52 模式
.	Del	CSI 3 ~	CSI 3 ~
0	Ins	CSI 2 ~	CSI 2 ~
1	End	CSI F	ESC F
2	Down	CSI B	ESC B
3	PgDn	CSI 6 ~	CSI 6 ~
4	Left	CSI D	ESC D
4	Clear	CSI E	ESC E
6	Right	CSI C	ESC C
7	Home	CSI H	ESC H
8	Up	CSI A	ESC A
9	PgUp	CSI 5 ~	CSI 5 ~

当 DECKPAM（Alternate/Application Keypad Mode）被设置时，Shift 对小键盘的作用改变：此时生成的序列对应 VT100/V52 小键盘键（? 为中间字符），VT52 模式下不受任何其他修饰键影响，且仅在 Num Lock 关闭时生效：

键	别名	ANSI 模式	VT52 模式
.	Del	SS3 2 n	ESC ? n
0	Ins	SS3 2 p	ESC ? p
1	End	SS3 2 q	ESC ? q
2	Down	SS3 2 r	ESC ? r
3	PgDn	SS3 2 s	ESC ? s
4	Left	SS3 2 t	ESC ? t
4	Clear	SS3 2 u	ESC ? u
6	Right	SS3 2 v	ESC ? v
7	Home	SS3 2 w	ESC ? w
8	Up	SS3 2 x	ESC ? x
9	PgUp	SS3 2 y	ESC ? y

DECKPAM 还会影响小键盘的“算术”键（包括 Enter）：生成的序列大致对应 VT100/VT52 的算术键，且无需 Shift 即生效（VT52 模式下其余修饰键全部忽略），同样只在 Num Lock 关闭时生效：

键	ANSI 模式	VT52 模式
*	SS3 j	ESC ? j
+	SS3 k	ESC ? k
-	SS3 m	ESC ? m
/	SS3 o	ESC ? o
Enter	SS3 M	ESC ? M

七、图形模式字符集

ESC F / ESC G（Enter/Exit Graphics Mode）通过 Designate94Charset 将 G0 字符集切换到 DecSpecialGraphics 或切回 ASCII（OutputStateMachineEngine.cpp#L358-L363）。字符映射表定义在适配器层的 charsets.hpp 中。

spec 给出了基于 VT102 User Guide 描述的完整建议映射表（下表的“ASCII 字符”列为图形模式下应被重映射的源字符）：

ASCII 字符	映射字形	Unicode 值	说明
_	（空格）	U+0020	Blank
`	（空格）	U+0020	Reserved
a	█	U+2588	Solid rectangle
b	⅟	U+215F	1/
c	³	U+00B3	3/
d	⁵	U+2075	5/
e	⁷	U+2077	7/
f	°	U+00B0	Degrees
g	±	U+00B1	Plus or minus
h	→	U+2192	Right arrow
i	…	U+2026	Ellipsis (dots)
j	÷	U+00F7	Divide by
k	↓	U+2193	Down arrow
l	⎺	U+23BA	Bar at scan 0
m	⎺	U+23BA	Bar at scan 1
n	⎻	U+23BB	Bar at scan 2
o	⎻	U+23BB	Bar at scan 3
p	⎼	U+23BC	Bar at scan 4
q	⎼	U+23BC	Bar at scan 5
r	⎽	U+23BD	Bar at scan 6
s	⎽	U+23BD	Bar at scan 7
t	₀	U+2080	Subscript 0
u	₁	U+2081	Subscript 1
v	₂	U+2082	Subscript 2
w	₃	U+2083	Subscript 3
x	₄	U+2084	Subscript 4
y	₅	U+2085	Subscript 5
z	₆	U+2086	Subscript 6
{	₇	U+2087	Subscript 7
\	₈	U+2088	Subscript 8
}	₉	U+2089	Subscript 9
~	¶	U+00B6	Paragraph

spec 同时解释了表中两处不得不做的取舍：Unicode 里只有一个“分数分子”字符（U+215F，1/），所以分子 3、5、7 改用上标数字（³、⁵、⁷）表示；Unicode 的“水平扫描线”字符（U+23BA–U+23BD）数量不够覆盖 8 个 scan 位置，因此每个字符被复用两次（scan 0/1 同为 ⎺，以此类推）。

八、测试策略与仓库中的对应实现

spec 的 Testing 一节规划了四层验证手段，仓库中均可找到对应物：

1. 适配器单元测试：在 AdapterTest 中确认对 AdaptDispatch 的 ANSI/VT52 模式切换调用会被正确转发到 ConGetSet 接口对应的 PrivateXXX 处理器。仓库对应文件为 adapterTest.cpp，其中已包含 VT52 相关用例。
2. 状态机引擎测试（主体）：验证各类 VT52 序列在 VT52 模式开启时触发 ITermDispatch 的期望方法、在 ANSI 模式下不产生任何效果。spec 中的 StateMachineExternalTest 对应仓库当前的 OutputEngineTest.cpp（另见 StateMachineTest.cpp 中对 ActionVt52EscDispatch 的引擎 mock）。
3. 无需新增屏幕缓冲测试：因为复用的是已有 VT100 功能，ScreenBufferTests 侧已有覆盖。
4. 模糊测试（fuzzing）：需要在 VTCommandFuzzer 的私有模式参数生成中加入 DECANM，并为 Direct Cursor Address（带参数）和无参数命令各加一个 token 生成器。仓库中 VTCommandFuzzer.cpp 已包含 VT52 相关序列的生成逻辑。

手动测试方面，spec 建议使用 Vttest 工具的 “Test of VT52 mode” 选项确认显示行为，并顺带过一遍 “Test of keyboard” 部分——那些测试并非只为后期 VT 型号设计，同样覆盖 VT52 键盘。

九、兼容性、性能与后续影响

spec 的 Capabilities 一节给出了明确的能力评估，值得逐条继承：

• 兼容性（唯一的破坏性风险）：把 VT52 命令收进独立模式后，依赖“不切模式就能收到少量 VT52 命令”的旧代码会受影响；但该行为本身是非标准的、且存在时间不长。spec 的结论是：实现缺失的 VT100 功能（如 IND）的收益明显大于保留这种非标准行为。
• 无障碍：不产生超出现有转义序列的额外影响。
• 安全性与可靠性：不引入新的安全问题或可靠性问题。
• 性能、功耗与效率：StateMachine 与 TerminalInput 中新增的模式标志及其处理可能带来一定性能影响，但预计不显著。
• UI/UX：该功能没有任何新增界面。

“Future considerations” 则点明了整个工程的战略价值：VT52 功能被隔离到新模式之后，VT100 的 Index（IND）序列便可实现——这正是当初被 ESC I 冲突卡住的那条命令。从当前源码看，IND 已能走正常的 CSI 路径而不再与 VT52 的 Reverse Line Feed 争抢。

十、延伸阅读

• 设计文档本体：VT52 escape sequences spec
• 状态机核心实现：stateMachine.hpp、stateMachine.cpp
• VT52 命令分派：OutputStateMachineEngine.cpp#L342-L400
• 模式管理（DECANM/DECKPAM/DECNKM）：adaptDispatch.cpp
• 键盘序列生成：terminalInput.cpp
• 背景规范（spec Resources 一节所列，供线下查阅）：DEC STD 070 Video Systems Reference Manual、VT100 User Guide 第 3 章（VT52 Mode Control Sequences、DECANM、IND 条目）、VTTEST 测试工具