Skip to content

README.org

Latest commit

 

History

History
324 lines (246 loc) · 9.94 KB

README.org

File metadata and controls

324 lines (246 loc) · 9.94 KB
Raw

Vim 9 Workbench

概览

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

.vimrc
└── vimrc/
    ├── core.vim       核心选项、undo/swap/state
    ├── plugins.vim    插件配置与 SimplePlug 清单
    ├── behavior.vim   FileType、健康检查、兼容层
    └── mappings.vim   所有真实键位与 WhichKey 描述

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

设计原则：

  • 默认离线：启动 Vim 不会自动 clone、更新插件或下载语言服务器。
  • 可降级：SimplePlug 或所有插件都不存在时，Vim 的核心编辑能力仍能正常启动。
  • 可恢复：启用 swap、write-backup 和 persistent undo，状态统一放在 XDG state。
  • 单一键位来源：插件默认映射尽量关闭，真实 mapping 与 WhichKey 描述放在一起。
  • 可验证：同时提供空 HOME 核心测试和本机完整插件栈测试。

要求

运行时

  • Vim 9.1 或更新版本。
  • 必需特性：=+vim9script=、=+job=、=+channel=、=+timers=、 =+popupwin=、=+textprop=、=+persistent_undo=。
  • Git：插件安装、更新及 SimpleGit。
  • Nerd Font 可选；当前 UI 默认使用 Nerd Font 图标。

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

构建插件

八个 simple* 插件包含 Rust 后端。首次构建推荐：

  • Bash
  • Rust/Cargo 1.85 或更新版本
  • 各插件安装脚本所需的系统开发库

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

安装

1. 只安装核心配置（默认、完全离线）

./utils/install.sh

安装器会：

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

预览操作而不写入：

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

2. 安装完整 Vim 配置入口

./utils/install.sh --profile full

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

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

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

3. 显式安装 SimplePlug

这是唯一会下载并编译代码的安装步骤：

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

安装器固定到已审计的 SimplePlug revision，在临时目录中构建和验证成功后再切换 到 =~/.vim/plugged/simpleplug=。每次显式 bootstrap 都会重新构建该 revision，不会 信任已有工作树或二进制；任何阶段失败都会恢复本轮替换前的配置和插件。它不会顺带 安装其他插件。

然后在 Vim 中显式执行：

:PlugInstall

插件更新同样是显式操作：

:PlugStatus
:PlugUpdate

安全与状态

Vim 状态默认写入：

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

配置默认设置：

g:simpleplug_auto_install = 0
g:simplecc_auto_install = 0

因此打开 Vim 或源文件不会隐式联网。语言服务器通过 :SimpleCCInstall 按需安装。 SimpleCC 配置中的 command / args 会启动本地进程，因此默认只信任这个仓库或 用户级 XDG 配置，不自动信任刚打开项目里的配置。

机器专属设置放在 =~/.vimrc.local=，例如：

vim9script
set ambiwidth=single

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

g:simplecc_config_path = ''

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

插件职责

组件职责
SimplePlug安全的异步插件安装、更新和状态检查
SimpleFinder文件、buffer、recent 和全文搜索
SimpleTree异步文件树
SimpleLine状态栏与 buffer tabline
SimpleMinimap代码缩略图
SimpleTreeSitterTree-sitter 高亮与 outline
SimpleCCLSP、补全、诊断、格式化和代码导航
SimpleClipboard=-clipboard=、SSH、容器和 OSC52 剪贴板降级
SimpleGit行内 blame、文件历史、diff、仓库状态与 hunk 操作
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>h清除搜索高亮
<leader>cw清理当前 buffer 尾随空白
<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在文件树中定位当前文件

LSP

键位功能
gd / gr定义 / 引用
KHover 文档
gi / gy实现 / 类型定义
[d / ]d上一条 / 下一条诊断
<leader>la/ln/lfCode 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/gdGit 状态 / blame 侧栏 / diff
<leader>gh/gm/gt文件历史 / 行 blame / 行内注解开关
<leader>gp/ga/gu预览 / stage / undo hunk
<leader>cc注释当前行或可视范围
<leader>jjEasyMotion 跨窗口跳转
<leader>th/to/tsTree-sitter 开关 / outline / 状态
<leader>mm/mf/msMinimap 开关 / 聚焦 / 风格
<leader>tt/tn/tp/tN终端开关 / 新建 / 上一个 / 下一个
<leader>y复制到系统剪贴板
<leader>1 … <leader>0跳到 SimpleLine 显示的 buffer 索引

按 <leader> 或 <localleader> 可打开 WhichKey。

语言服务器

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 配置路径；
  • FileType 局部设置互不泄漏；
  • 配置连续 source 两次；
  • SimpleCC 映射无尾随空格；
  • lexima 与补全 Enter 兼容；
  • SimpleTree/SimpleMinimap 状态栏不被 SimpleLine 覆盖。

常用诊断：

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

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

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