Vim 9 Workbench

概览

这是一个以 Vim 9 + Vim9script 为核心的个人开发工作台。配置保留了 beamiter/simple* 插件生态，同时把基础编辑能力、插件层、行为逻辑和键位层分开：

.vimrc
└── config/
    ├── core.vim       核心选项、undo/swap/state
    ├── bootstrap.vim  首次启动自动安装 SimplePlug 并接续 PlugUpdate
    ├── plugins.vim    插件配置与 SimplePlug 清单
    ├── behavior.vim   FileType、健康检查、兼容层
    ├── workflow.vim   大文件保护、项目根目录、quickfix 工作流
    ├── mappings.vim   所有真实键位与 SimpleWhichKey 描述
    └── update.vim     配置仓库更新检查（只读 fetch，拉取需显式执行）

只需要链接一个 =~/.vimrc=。顶层配置会根据自身真实路径加载其他模块，因此仓库不必固定放在 =~/vimrc=。

设计原则：

一次启动完成：SimplePlug 缺失时自动在后台获取最新主分支、构建并原子启用；成功后自动接续 =:PlugUpdate=，最后重载配置，让新插件在当前会话直接可用。
安装器离线、首次启动联网：=utils/install.sh= 默认只创建链接，不访问网络；真正的插件下载从用户第一次打开 Vim 后开始。语言服务器仍不会自动下载。
可降级：SimplePlug 或所有插件都不存在时，Vim 的核心编辑能力仍能正常启动。
可恢复：启用 swap、write-backup 和 persistent undo，状态统一放在 XDG state。
项目友好：自动读取 =.editorconfig=，并能从当前文件向上发现工作区根目录。
大文件可控：超过 5 MiB 自动关闭当前 buffer 的高成本显示和恢复特性。
单一键位来源：插件默认映射尽量关闭，真实 mapping 与 SimpleWhichKey 描述放在一起；没写描述的键位，面板直接从 mapping 的 rhs 里读。
可验证：同时提供空 HOME 核心测试和本机完整插件栈测试。

要求

运行时

Vim 9.1 或更新版本。
必需特性：=+vim9script=、=+job=、=+channel=、=+timers=、 =+popupwin=、=+textprop=、=+persistent_undo=。
Git：插件安装、更新及 SimpleGit。
Bash 与可访问 GitHub 的网络：首次自动配置需要。
Nerd Font 可选；当前 UI 默认使用 Nerd Font 图标。

执行 :VimrcHealth 可以检查当前环境。

构建插件

八个 simple* 插件包含 Rust 后端。自动 bootstrap 会直接调用各仓库自己的 =install.sh=，因此需要：

Bash
Rust/Cargo 满足插件当前的 MSRV（SimplePlug 当前要求 1.88 或更新版本）
各插件安装脚本所需的系统开发库

不构建插件也不影响核心模式。

安装

1. 链接配置（默认、这一步完全离线）

./utils/install.sh

安装器会：

从脚本自身定位仓库；
安全备份已有 =~/.vimrc=；
创建绝对符号链接；
重复执行时保持幂等；
不调用 git、cargo、Vim、sudo 或包管理器。

预览操作而不写入：

./utils/install.sh --dry-run

2. 打开 Vim，自动完成全部配置

vim

首次启动会自动完成下面的单次流水线，无需退出、重开或输入命令：

VimEnter
  → 后台 clone SimplePlug 最新默认分支
  → 在私有 staging 目录构建并验证 daemon
  → 原子启用 SimplePlug
  → 自动重载 vimrc
  → 自动 :PlugUpdate（安装其余插件并执行可信 hook）
  → 更新完成后再次重载，关闭进度窗并回到原编辑窗口

bootstrap 期间核心编辑能力已经可用。失败不会留下半成品，也不会退出 Vim；可用 :VimrcBootstrapStatus 查看最近日志，修复网络或 Rust 环境后执行 :VimrcBootstrapRetry=。:VimrcBootstrapStop= 可停止仍在运行的 bootstrap。

3. 可选：同时安装全局 SimpleCC 配置入口

./utils/install.sh --profile full

full 会额外把 simplecc.json 链接到：

${XDG_CONFIG_HOME:-$HOME/.config}/simplecc/simplecc.json

.vimrc 会显式指定这个用户级配置；未安装 full 时则显式使用仓库内的 simplecc.json=。项目中的 =simplecc.json 默认不会被自动读取。

4. 可选：在打开 Vim 前预先安装 SimplePlug

通常不需要这一步；若希望先在 shell 中完成管理器构建，可执行：

./utils/install.sh --bootstrap-simpleplug

该选项获取远端当前默认分支，在私有 staging 目录完成构建和验证后才替换管理器；已有目录会保存在 =.vimrc-bootstrap-backups/=。随后只需打开 Vim，SimplePlug 会自动补装其余缺失插件。

日常检查和完整更新仍可显式执行：

:PlugStatus
:PlugUpdate

配置自身的更新检查

启动完成后（=VimEnter= 之后约 0.8 秒）会异步执行一次 git fetch --quiet --no-tags=，然后比较本地 =HEAD 与 upstream。落后时提示：

[vimrc] 配置落后 origin/master 3 个提交，运行 :VimrcUpdate 拉取

fetch 在后台 job 中进行，不阻塞启动；超时后 job 会被终止。检查结果保存在 g:vimrc_update_status=（=upstream / ahead / behind / =checked=）。节流时间戳文件在 =${XDG_STATE_HOME:-$HOME/.local/state}/vim/update-check=。

同一份状态还会渲染到 statusline 上：落后时 SimpleLine 右侧出现 󰚰 3=（=SimpleLineDiagWarn 高亮），已是最新则不占位置。实现是 SimpleLine 的用户段位接口 g:simpleline_custom_right=，=config/update.vim 注册 g:VimrcUpdateStatusline 进去；该函数只读 =g:vimrc_update_status=，不会在重画时跑 git。SimpleLine 版本过旧（没有这个接口）时段位不显示，其余功能不受影响。

命令	功能
`:VimrcUpdateCheck`	忽略节流，立刻检查一次并汇报结果
`:VimrcUpdate`	=git pull –ff-only=；工作区有未提交改动时拒绝执行
`:VimrcReload`	重新 source `~/.vimrc`

对应键位：=<leader>vc= 检查，=<leader>vu= 更新，=<leader>vr= 重载。

可调项（放在 =~/.vimrc.local=）：

let g:vimrc_update_check = 0        " 完全关闭自动检查
let g:vimrc_update_interval = 3600  " 自动检查最小间隔（秒），默认 86400
let g:vimrc_update_delay = 2000     " 启动后延迟多久 fetch（毫秒），默认 800
let g:vimrc_update_timeout = 10000  " fetch 超时（毫秒），默认 20000

环境变量 VIMRC_SKIP_UPDATE_CHECK=1 等价于关闭自动检查；=utils/check.sh= 会自动设置它，测试始终不联网。

自动检查只覆盖配置仓库。插件首次配置会自动执行一次完整 =:PlugUpdate=；以后新增但缺失的插件会由 SimplePlug 自动补装，已有插件的日常完整更新仍由 :PlugUpdate 显式触发。

安全与状态

Vim 状态默认写入：

${XDG_STATE_HOME:-$HOME/.local/state}/vim/
├── undo/
├── swap/
├── backup/
├── session/
└── viminfo

=undofile=：跨会话撤销。
=swapfile=：崩溃恢复。
=writebackup=：写入过程中保留临时保护副本。
nobackup=：成功写入后不长期保留 =~ 文件。
=viminfo=：marks、registers、命令历史和 oldfiles。
SimpleStartify session 只存放在权限受控的 state 目录。
如果 state 目录无法创建或写入，undo、swap 和 write-backup 会关闭，不会退回到项目目录生成恢复文件。
无效或指向根目录的 XDG 路径会被忽略；无效的 HOME 会直接停止加载，避免向当前目录或文件系统根目录写状态。

配置默认设置：

g:simpleplug_auto_install = 1
g:simplecc_auto_install = 0

因此新增插件会自动补齐，但语言服务器仍通过 :SimpleCCInstall 按需安装。 SimpleCC 配置中的 command / args 会启动本地进程，因此默认只信任这个仓库或用户级 XDG 配置，不自动信任刚打开项目里的配置。

若需要完全离线启动，可在 ~/.vimrc.before 中关闭两层自动化：

vim9script
g:vimrc_simpleplug_auto_bootstrap = 0
g:simpleplug_auto_install = 0

一次性环境变量 VIMRC_SKIP_SIMPLEPLUG_BOOTSTRAP=1 只关闭管理器 bootstrap； VIMRC_SKIP_PLUGINS=1 会跳过整个插件层。首次更新等待上限默认一小时，可通过 g:vimrc_simpleplug_update_timeout 调整（秒）。

需要在插件加载之前生效的机器设置放在 ~/.vimrc.before=，例如 leader、插件目录和 =g:simple* 选项：

vim9script
g:vimrc_plugin_home = '/data/vim/plugged'
g:simplecc_semantic_tokens = 1

普通机器专属设置放在 =~/.vimrc.local=，它在所有共享模块之后加载，例如：

vim9script
set ambiwidth=single

两个文件都可选且不进入版本控制。可调的核心开关：

g:vimrc_editorconfig = 0          # 不加载 Vim runtime 的 EditorConfig
g:vimrc_highlight_yank = 0        # 不高亮刚复制的文本
g:vimrc_large_file_bytes = 0      # 关闭大文件模式（默认 5 MiB）
g:vimrc_root_markers = ['.git']   # 自定义项目根标记

为防止刚打开的项目执行未信任配置，默认启用 nomodeline 和 =noexrc=。

如果确实信任所有会打开的项目，可以显式恢复 SimpleCC 的项目优先发现：

g:simplecc_config_path = ''

注意：项目配置可指定任意 =command= / =args=，这等同于允许项目在 SimpleCC 启动时执行本地命令。 原生全局发现路径是 =~/.config/simplecc/simplecc.json=；它不识别非默认 =XDG_CONFIG_HOME=。

插件职责

组件	职责
SimplePlug	安全的异步插件安装、更新和状态检查
SimpleFinder	文件、buffer、recent 和全文搜索
SimpleTree	异步文件树
SimpleLine	状态栏与 buffer tabline
SimpleMinimap	代码缩略图
SimpleTreeSitter	Tree-sitter 高亮与 outline
SimpleCC	LSP、补全、诊断、格式化和代码导航
SimpleClipboard	=-clipboard=、SSH、容器和 OSC52 剪贴板降级
SimpleGit	行内 blame、文件历史、diff、仓库状态与 hunk 操作
SimpleWhichKey	所有前缀键的实时提示面板（含 Vim 原生前缀）
SimpleStartify	随机启动页、recent 文件与受控 session 管理
lexima + tcomment + matchup	配对输入、注释和括号匹配

已移除两个会在空 buffer 触发错误且与现有能力重叠的插件：

=vim-polyglot=：改用 Vim 9 runtime、语言专用插件和 SimpleTreeSitter。
=vim-better-whitespace=：改为内建、可测试的尾随空白高亮与清理。

键位

Leader 为 =Space=，LocalLeader 为 =,=。

通用

键位	功能
`<leader>fs`	保存当前文件（仅有改动时）
`<leader>fS`	保存所有文件
`<leader>ve` / `vr`	编辑 / 重载配置
`<leader>vh`	运行 `:VimrcHealth`
`<leader>vc` / `vu`	检查配置更新 / 拉取配置更新
`<leader>h`	清除搜索高亮
`<leader>cw`	清理当前 buffer 尾随空白
`<leader>fd`	当前窗口切换到项目根目录
`<leader>qq/ql`	开关 quickfix / location list
`<leader>qn/qp`	下一条 / 上一条 quickfix
`<C-h/j/k/l>`	窗口导航
`<leader>ww/ws/wv/wd`	切换 / 横分 / 竖分 / 关闭窗口
`<leader>bn/bk/bl/bd`	下一个 / 上一个 / alternate / 删除 buffer
`,1` … `,0`	跳到第 1 … 10 个窗口

原生 s=、=(=、)= 已恢复，不再被插件覆盖。

文件与搜索

键位	功能
`<leader>ff` / `<leader><Space>`	查找项目文件
`<leader>fr`	最近文件
`<leader>fb` / `bb`	查找 buffer
`<leader>fg` / `st`	实时全文搜索
`<leader>fw` / `sw`	搜索光标词或可视选择
`<leader>e` / `ft` / `F3`	文件树
`<leader>fT`	在文件树中定位当前文件

:VimrcRoot 使用 lcd=，只改变当前窗口目录；:VimrcRoot!= 使用全局 cd=。 =:VimrcLargeFile 显示当前 buffer 是否进入大文件模式以及实际阈值。进入大文件模式时 SimpleLine 右侧还会显示 =BIG <size>=。

LSP

键位	功能
`gd` / `gr`	定义 / 引用
`K`	Hover 文档
`gi` / `gy`	实现 / 类型定义
`[d` / `]d`	上一条 / 下一条诊断
`<leader>la/ln/lf`	Code action / rename / format
`<leader>lo/lw`	文档 outline / workspace symbol
`<leader>li/lR/ll`	状态 / 重启 / 日志
`<leader>lc/lC`	打开 / 热加载配置
`<leader>lI/lS`	安装 / 列出语言服务器
`<leader>ih` / `lp`	切换 inlay hints

SimpleCC 的默认 mapping 已关闭。显式 mapping 修复了旧版本部分 RHS 尾随空格的问题；=gd/gr/K/gi/gy/[d/]d= 仅在配置了语言服务器的代码 buffer 内覆盖， Insert 模式的 Tab、Shift-Tab 和补全上下选择同样只在这些 buffer 内接管；其他 buffer 保留 Vim/lexima 的原行为。Enter 补全确认与 lexima 的括号换行也已组合处理。

Git、工具与 UI

键位	功能
`[g` / `]g`	上一个 / 下一个 Git hunk
`<leader>gs/gb/gd`	Git 状态 / blame 侧栏 / diff
`<leader>gh/gm/gt`	文件历史 / 行 blame / 行内注解开关
`<leader>gp/ga/gu`	预览 / stage / undo hunk
`<leader>cc`	注释当前行或可视范围
`<leader>jj`	EasyMotion 跨窗口跳转
`<leader>th/to/ts`	Tree-sitter 开关 / outline / 状态
`<leader>mm/mf/ms`	Minimap 开关 / 聚焦 / 风格
`<leader>pp/pf/po`	Markdown 预览开关 / 聚焦 / 目录
`<leader>pr/ps/ph`	预览重绘 / 切换装饰字符 / 健康检查
`<leader>pb/pB/pq`	浏览器预览开关 / 静态渲染一次 / 停掉全部（需 =omd=）
`<leader>pn/pz/pu`	预览开关：代码行号 / 表格斑马纹 / 链接目标
`<leader>tt/tn/tp/tN`	终端开关 / 新建 / 上一个 / 下一个
`<leader>y`	复制到系统剪贴板
`<leader>1` … `<leader>0`	跳到 SimpleLine 显示的 buffer 索引

键位提示

停在任何前缀键上不动，SimpleWhichKey 就会把下一个键的所有可能列出来——不只是 <leader> 和 =<localleader>=，还包括 Vim 自己的前缀：

前缀	面板内容
`<leader>` / `<localleader>`	本配置和插件的映射，带上面这些描述
`<C-w>`	Vim 全部窗口命令
`g` / `z` / `Z`	跳转、折叠与滚动、退出命令，混入同前缀的映射
`[` / `]`	原生跳转加上 `]q` / `]g` 这类映射
`"`	当前真正有内容的寄存器，带内容预览
`'` / `	当前真正设置过的 mark，带文件与行号

面板里 <BS> 回上一层，=<Esc>= 关掉且不执行任何东西，没列出的键照常执行。按得快时面板不会出现：只有停顿超过 =g:simplewhichkey_delay=（本配置 180ms）才弹出，前缀下还有更长映射时由 =’timeoutlen’=（本配置 450ms）决定。

:SimpleWhichKeyHealth 报告每个前缀是否挂上；=<leader>0= … <leader>9 这类 buffer 索引键位刻意不进面板（=g:simplewhichkey_ignore=）。

语言服务器

simplecc.json 提供 Rust、C/C++、Python、Go、JavaScript/TypeScript、Lua 和 Julia 配置。自动安装关闭；缺失的服务器按需执行：

:SimpleCCServers
:SimpleCCInstall rust-analyzer
:SimpleCCInstall clangd
:SimpleCCInstall pyright
:SimpleCCInstall typescript-language-server
:SimpleCCInstall lua-language-server
:SimpleCCInstall gopls
:SimpleCCInstall julia-lsp

修改 settings 后可使用 =:SimpleCCReloadConfig=；修改 command、args、 filetypes、rootPatterns、priority 或 initializationOptions 后使用 =:SimpleCCRestart=。

检查与排障

默认检查不需要插件，也不联网：

./utils/check.sh

完整检查会使用本机已安装插件及 Rust 后端：

./utils/check.sh --full

检查内容包括：

安装器 Bash 语法、dry-run、备份、幂等和失败事务回滚；
simplecc.json JSON 语法；
空 HOME、无插件 Vim 启动；
无效 HOME/XDG 以及 state 不可写时的 fail-closed 行为；
非默认 XDG_CONFIG_HOME 的 SimpleCC 配置路径；
前置/后置本机配置和自定义 leader；
FileType 局部设置互不泄漏；
项目根目录、quickfix 开关和大文件自动保护；
配置连续 source 两次；
SimpleCC 映射无尾随空格；
lexima 与补全 Enter 兼容；
SimpleTree/SimpleMinimap 状态栏不被 SimpleLine 覆盖。
SimpleStartify 启动页可加载，且连续随机布局不会立即重复。

常用诊断：

:VimrcHealth
:VimrcUpdateCheck
:PlugStatus
:SimpleLineHealth
:SimpleTreeHealth
:SimpleMinimapHealth
:SimpleStartifyHealth
:SimpleCopyStatus
:TsHlStatus
:SimpleCC

如果 Nerd Font 图标错位，可在 ~/.vimrc.local 中使用：

set ambiwidth=single
g:simpleline_nerdfont = 0
g:simpletree_use_nerdfont = 0

Name		Name	Last commit message	Last commit date
Latest commit History 1,051 Commits
config		config
test		test
utils		utils
.vimrc		.vimrc
.vimspector.json		.vimspector.json
README.org		README.org
change_core_pattern.sh		change_core_pattern.sh
deps.sh		deps.sh
set_proxy.bash		set_proxy.bash
simplecc.json		simplecc.json
tunel0.sh		tunel0.sh
tunel1.sh		tunel1.sh
unset_proxy.bash		unset_proxy.bash

Navigation Menu

Repository files navigation

Vim 9 Workbench

概览

要求

运行时

构建插件

安装

1. 链接配置（默认、这一步完全离线）

2. 打开 Vim，自动完成全部配置

3. 可选：同时安装全局 SimpleCC 配置入口

4. 可选：在打开 Vim 前预先安装 SimplePlug

配置自身的更新检查

安全与状态

插件职责

键位

通用

文件与搜索

LSP

Git、工具与 UI

键位提示

语言服务器

检查与排障

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Vim 9 Workbench

概览

要求

运行时

构建插件

安装

1. 链接配置（默认、这一步完全离线）

2. 打开 Vim，自动完成全部配置

3. 可选：同时安装全局 SimpleCC 配置入口

4. 可选：在打开 Vim 前预先安装 SimplePlug

配置自身的更新检查

安全与状态

插件职责

键位

通用

文件与搜索

LSP

Git、工具与 UI

键位提示

语言服务器

检查与排障

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages