Helix 可输入命令（Typable Commands）全解：命令模式全量命令参考与源码级执行机制

本文围绕 Helix 官方手册中的 typable commands 参考表展开，完整收录全部内置可输入命令及其别名，并结合 命令定义源码、命令行解析模块 与 文档生成器，讲清命令模式（command mode）的参数签名、补全、执行与校验机制，读完即可在 Helix 中自如地用 : 前缀命令管理缓冲、写盘、剪贴板、LSP 与 shell 管道。

一、什么是 Typable Command

Helix 的命令分为两类（见 Commands 文档页）：

• Typable commands（可输入命令）：只能在命令模式中使用，按 : 进入命令模式后以 :command [args] 的形式键入，多数可携带参数；
• Static commands（静态命令）：不接受参数，可绑定按键，也可通过命令选择器（<space>?）执行。

本文聚焦前者。官方参考表 typable-cmd.md 是一份由源码自动生成的 Markdown 表格，它逐条列出了命令名、别名与描述——这正是本文命令全量参考的内容来源。

二、参考表如何从源码生成

从源码结构看，这份表格并非手维护的文档，而是构建期产物：

1. xtask/src/docgen.rs 中的 typable_commands() 遍历 helix_term::commands::TYPABLE_COMMAND_LIST，把每个命令的主名与 aliases 用逗号拼接成 `:name`, `:alias` 形式，并将 doc 中的换行替换为 <br> 后写入表格，最终落盘为 book/src/generated/typable-cmd.md（输出常量见 docgen.rs#L13）；
2. book/src/commands.md 通过 {{#include ./generated/typable-cmd.md}} 将其嵌入手册的 "Typable commands" 小节；
3. 命令清单本体定义在 helix-term/src/commands/typed.rs，是一个静态常量数组 TYPABLE_COMMAND_LIST，文件共 4600 余行，几乎每个可输入命令都在此注册。

每条命令在源码中是一个 TypableCommand 结构体（typed.rs#L20-L30）：

pub struct TypableCommand {
    pub name: &'static str,
    pub aliases: &'static [&'static str],
    pub doc: &'static str,
    pub fun: fn(&mut compositor::Context, Args, PromptEvent) -> anyhow::Result<()>,
    pub completer: CommandCompleter,   // 参数补全器
    pub signature: Signature,          // 参数签名
}

以 :exit 为例（typed.rs#L3007-L3018）：

TypableCommand {
    name: "exit",
    aliases: &["x", "xit"],
    doc: "Write changes to disk if the buffer is modified and then quit. Accepts an optional path (:exit some/path.txt).",
    fun: exit,
    completer: CommandCompleter::positional(&[completers::filename]),
    signature: Signature {
        positionals: (0, Some(1)),   // 0~1 个位置参数
        flags: &[WRITE_NO_FORMAT_FLAG, WRITE_NO_CODE_ACTIONS_FLAG],
        ..Signature::DEFAULT
    },
},

几个关键点：

• positionals: (min, Option<max>)：声明位置参数数量范围。(0, Some(1)) 表示 0 或 1 个参数，(1, None) 表示至少 1 个、上不封顶。该约束在按 <ret> 提交命令时校验，超出范围会报错而不执行（见 Signature 结构定义 的注释：例如 :write a.txt b.txt 会被拒绝）。
• completer：决定 Tab 补全行为，如 completers::filename（文件名）、completers::buffer（缓冲区名）、completers::theme（主题名）。
• flags：命令支持 Unix 风格的 --flag。写盘族命令统一支持 --no-format 与 --no-code-actions（定义见 typed.rs#L2994-L3004），用于在保存时跳过自动格式化和 LSP code actions。

三、命令模式的执行流程

按 : 触发 command_mode() 后，编辑器压入一个带 : 前缀的 Prompt 层，输入过程由 complete_command_line 驱动模糊补全：输入前缀会在 TYPABLE_COMMAND_LIST 的主命令名上做 fuzzy match（typed.rs#L4259-L4269）。提交时进入 execute_command_line（typed.rs#L4125-L4146）：

let (command, rest, _) = command_line::split(input);
// 若命令是纯数字且无参数，等价于 :goto 跳到该行
if command.parse::<usize>().is_ok() && rest.trim().is_empty() {
    let cmd = TYPABLE_COMMAND_MAP.get("goto").unwrap();
    return execute_command(cx, cmd, command, event);
}

其中 split() 按空格/Tab 把输入切分为「命令名」与「剩余参数」，并判断当前是否处于补全命令名阶段。随后按名查表：

• 查找用的 TYPABLE_COMMAND_MAP 是一张把主名与全部别名都映射到同一命令的 HashMap（typed.rs#L4114-L4123），这就是 :x、:xit、:exit 三者等效的原因；
• 查不到命令时返回 no such command: '...' 错误显示在状态栏；
• 命中后 execute_command（typed.rs#L4148-L4165）用 Args::parse 依据该命令的 Signature 解析参数（提交时会做严格校验与变量展开，补全阶段宽松解析），最后调用 cmd.fun(cx, args, event)。

另外，Prompt 的文档行会由 command_line_doc 动态生成（typed.rs#L4186-L4197）：命令有别名或 flags 时，提示行会额外列出 Aliases: 和每个 flag 的说明，输入时可直接看到可用标志。

四、全量命令参考（按功能域分组）

以下为 typable-cmd.md 中全部 100 条命令的完整继承与分组整理，描述与官方生成表一致。

4.1 保存与退出

Name	Description
:exit, :x, :xit	若缓冲区已修改则写盘，然后退出。可带可选路径（:exit some/path.txt）。
:exit!, :x!, :xit!	强制写盘（必要时创建子目录），然后退出。可带可选路径。
:write-quit, :wq	写盘并关闭当前 view。可带可选路径。
:write-quit!, :wq!	强制写盘并关闭当前 view。可带可选路径。
:write-quit-all, :wqa, :xa	写所有缓冲区到磁盘并关闭所有 view。
:write-quit-all!, :wqa!, :xa!	强制写所有缓冲区（创建必要子目录）并关闭所有 view（忽略未保存修改）。
:quit, :q	关闭当前 view。
:quit!, :q!	强制关闭当前 view，忽略未保存修改。
:quit-all, :qa	关闭所有 view。
:quit-all!, :qa!	强制关闭所有 view，忽略未保存修改。
:cquit, :cq	以退出码退出（默认 1），可指定整数（:cq 2）。
:cquit!, :cq!	强制以退出码退出，忽略未保存修改。

源码佐证：exit/quit 的实现见 typed.rs#L71-L120。exit 仅在 is_modified() 为真时调用 write_impl（force: false），随后 quit；force_exit 则传 force: true。关闭前会 block_try_flush_writes() 等待异步写入完成。

4.2 打开与缓冲区管理

Name	Description
:open, :o, :edit, :e	从磁盘打开文件到当前 view。
:read, :r	把文件读入当前缓冲区。
:new, :n	创建一个 scratch 缓冲区。
:buffer-close, :bc, :bclose	关闭当前缓冲区。
:buffer-close!, :bc!, :bclose!	强制关闭当前缓冲区，忽略未保存修改。
:buffer-close-others, :bco, :bcloseother	关闭除当前聚焦缓冲区外的所有缓冲区。
:buffer-close-others!, :bco!, :bcloseother!	强制关闭除当前聚焦缓冲区外的所有缓冲区。
:buffer-close-all, :bca, :bcloseall	关闭所有缓冲区（不退出编辑器）。
:buffer-close-all!, :bca!, :bcloseall!	强制关闭所有缓冲区，忽略未保存修改（不退出）。
:buffer-next, :bn, :bnext	切换到下一个缓冲区。
:buffer-previous, :bp, :bprev	切换到上一个缓冲区。

:open 的签名是 positionals: (1, None) 且补全器为 completers::filename，因此它必须至少带一个路径参数，输入空格后 Tab 可补全文件路径（typed.rs#L3053-L3063）。

4.3 写盘、移动与更新

Name	Description
:write, :w	写盘。可带可选路径（:write some/path.txt）。
:write!, :w!	强制写盘，创建必要子目录。可带可选路径。
:write-buffer-close, :wbc	写盘并关闭缓冲区。可带可选路径。
:write-buffer-close!, :wbc!	强制写盘（创建子目录）并关闭缓冲区。可带可选路径。
:write-all, :wa	写所有缓冲区到磁盘。
:write-all!, :wa!	强制写所有缓冲区，创建必要子目录。
:move, :mv	把当前缓冲区及其对应文件移动到新路径。
:move!, :mv!	同上，创建必要子目录。
:update, :u	仅当磁盘文件已变化时写回修改。

写盘族命令都携带 --no-format / --no-code-actions 两个 flag（typed.rs#L3146-L3169），例如 :write --no-format src/main.rs 可在保存时跳过格式化。

4.4 剪贴板与寄存器

Name	Description
:yank-join	以连接后的形式 yank 选区，第一个参数为分隔符，默认换行。
:clipboard-yank	将主选区复制到系统剪贴板。
:clipboard-yank-join	以连接形式将选区复制到系统剪贴板，可选分隔符参数。
:primary-clipboard-yank	将主选区复制到系统 primary 剪贴板。
:primary-clipboard-yank-join	以连接形式将选区复制到系统 primary 剪贴板，可选分隔符参数。
:clipboard-paste-after	在选区之后粘贴系统剪贴板内容。
:clipboard-paste-before	在选区之前粘贴系统剪贴板内容。
:clipboard-paste-replace	用系统剪贴板内容替换选区。
:primary-clipboard-paste-after	在选区之后粘贴 primary 剪贴板内容。
:primary-clipboard-paste-before	在选区之前粘贴 primary 剪贴板内容。
:primary-clipboard-paste-replace	用 primary 剪贴板内容替换选区。
:show-clipboard-provider	在状态栏显示当前剪贴板 provider 名称。
:clear-register	清空指定寄存器；不带参数则清空所有寄存器。
:set-register	设置指定寄存器的内容。
:yank-diagnostic	将主光标下的诊断信息 yank 到寄存器或默认到剪贴板。

寄存器语义详见手册 registers。

4.5 工作目录操作

Name	Description
:change-current-directory, :cd	更改当前工作目录。
:show-directory-stack	以空格分隔的字符串形式显示目录栈。
:push-directory, :pushd	保存当前目录后切换（压栈）。
:pop-directory, :popd	弹出目录栈顶，并 cd 到新的栈顶目录。
:show-directory, :pwd	显示当前工作目录。

4.6 文档属性、编码与文本处理

Name	Description
:encoding	设置文档编码（基于 WHATWG encoding 规范）。
:line-ending	设置文档默认行尾，选项：crlf、lf。
:indent-style	设置编辑缩进风格（t 表示 tab，1-16 表示空格数）。
:set-language, :lang	设置当前缓冲区的语言（不填参数时显示当前语言）。
:character-info, :char	显示主光标下字符的信息。
:sort	对选区内的行进行排序。
:reflow	将当前选中的行按指定宽度硬换行。
:reload, :rl	放弃修改并从源文件重新加载。
:reload-all, :rla	放弃修改并从源文件重新加载所有文档。

源码细节：:line-ending 的描述随构建 feature 变化——默认构建下选项为 crlf, lf；启用 unicode-lines feature 后扩展为 crlf, lf, cr, ff, nel（见 typed.rs#L3227-L3240 的 #[cfg(feature = "unicode-lines")] 分支）。

4.7 编辑历史

Name	Description
:earlier, :ear	回退到更早的编辑历史点，接受步数或时间跨度。
:later, :lat	前进到更晚的编辑历史点，接受步数或时间跨度。

4.8 LSP 与格式

Name	Description
:format, :fmt	使用外部格式化器或语言服务器格式化文件。
:lsp-workspace-command	打开 workspace 命令选择器。
:lsp-restart	重启指定语言服务器；不带参数时重启当前文件所用的全部语言服务器。
:lsp-stop	停止指定语言服务器；不带参数时停止当前文件所用的全部语言服务器。

LSP 集成背景可参考手册 lsp。

4.9 Tree-sitter 内省

Name	Description
:tree-sitter-scopes	显示 tree-sitter scope，主要用于主题开发与调试。
:tree-sitter-highlight-name	显示光标下 tree-sitter 高亮 scope 的名称。
:tree-sitter-layers	显示光标下 tree-sitter 注入层的语言名。
:tree-sitter-subtree, :ts-subtree	显示覆盖主选区的最小 tree-sitter 子树，主要用于调试查询。

4.10 调试（DAP）

Name	Description
:debug-start, :dbg	从给定模板并以给定参数启动调试会话。
:debug-remote, :dbg-tcp	通过 TCP 地址连接调试适配器，启动调试会话。
:debug-eval	在当前调试上下文中求值表达式。

4.11 视图与分屏

Name	Description
:vsplit, :vs	在垂直分屏中打开文件。
:vsplit-new, :vnew	在垂直分屏中打开 scratch 缓冲区。
:hsplit, :hs, :sp	在水平分屏中打开文件。
:hsplit-new, :hnew	在水平分屏中打开 scratch 缓冲区。
:goto, :g	跳转到指定行号。
:redraw	清除并重新渲染整个 UI。

小技巧：在命令模式直接输入纯数字（如 :42）无需打 goto——execute_command_line 会把纯数字行号透明地转换为 goto（typed.rs#L4135-L4139）。

4.12 运行时配置与日志

Name	Description
:set-option, :set	运行时设置配置项。例如禁用 smart case 搜索：:set search.smart-case false。
:toggle-option, :toggle	运行时切换配置项。例如：:toggle search.smart-case。
:get-option, :get	获取配置项当前值。
:theme	更改编辑器主题（不指定名称时显示当前主题）。
:config-reload	刷新用户配置。
:config-open	打开用户 config.toml 文件。
:config-open-workspace	打开 workspace config.toml 文件。
:log-open	打开 Helix 日志文件。

:theme 的位置参数补全器为 completers::theme，因此输入空格后 Tab 即可浏览 runtime/themes 与 contrib/themes 中的主题名。

4.13 Shell 管道

Name	Description
:insert-output	运行 shell 命令，把输出插入每个选区之前。
:append-output	运行 shell 命令，把输出追加到每个选区之后。
:pipe, :|	把每个选区通过管道传给 shell 命令（输出替换选区）。
:pipe-to	把每个选区通过管道传给 shell 命令，忽略其输出。
:run-shell-command, :sh, :!	运行一个 shell 命令。

4.14 Diff

Name	Description
:reset-diff-change, :diffget, :diffg	重置光标位置的 diff 变更。

4.15 Workspace Trust

Name	Description
:workspace-trust	允许当前 workspace 使用语言服务器和本地配置。
:workspace-untrust	撤销当前 workspace 的信任或排除授权。
:workspace-exclude	将当前 workspace 标记为永不提示，之后不再询问信任。

信任机制的完整语义见手册 workspace-trust。

4.16 其他

Name	Description
:tutor	打开教程（对应 runtime/tutor）。
:echo	将给定参数打印到状态栏。
:noop	什么都不做。

五、实战要点小结

1. 别名即命令：TYPABLE_COMMAND_MAP 将主名与别名统一建索引，所以 :x、:xit、:exit 走同一实现路径；写命令时优先用短别名提升效率。
2. 参数有签名约束：:open 必须带路径，:quit 不带参数；提交前由 Signature.positionals 校验，参数个数不符会报错且不执行。
3. 写盘族可用 flags 微调：:w、:wq、:wa 等支持 --no-format、--no-code-actions，适合在 LSP 尚未就绪或想保留原始格式时保存。
4. 模糊补全 + 文档提示：命令模式输入前缀即触发 fuzzy 补全，命令的别名与 flags 也会实时显示在提示区，降低记忆成本。
5. 数字即跳转：:42 等价于 :goto 42，是源码层面内建的语法糖。

六、延伸阅读

• 命令模式说明与静态命令表：book/src/commands.md、static-cmd.md
• 命令清单与执行引擎：helix-term/src/commands/typed.rs
• 命令行解析（split / Signature / Args / Flag）：helix-core/src/command_line.rs
• 参考表生成逻辑：xtask/src/docgen.rs
• 配置项（配合 :set / :toggle）：configuration 文档