docs(readme): 更新插件列表和懒加载表,新增 AGENTS.md 和 PLUGINS.md 文档

This commit is contained in:
xfy 2026-06-02 14:52:49 +08:00
parent 57f5c86a08
commit 593e983453
3 changed files with 128 additions and 9 deletions

77
AGENTS.md Normal file
View File

@ -0,0 +1,77 @@
# AGENTS.md
This is a personal Neovim configuration targeting **Neovim 0.12+**. It lives at `~/.config/nvim` and is **not** a traditional software project — there is no build system, test suite, or package manager outside Neovim itself.
## Critical Architecture Notes
- **Plugin manager**: Neovim 0.12+ built-in `vim.pack` (not lazy.nvim / packer). Plugins are declared in `lua/pack.lua` via `vim.pack.add({ urls }, { load = false })` and tracked in `nvim-pack-lock.json`.
- **Custom lazy-loading**: `lua/lazy.lua` is a ~35-line custom framework (unrelated to lazy.nvim). It provides `load()`, `on_event()`, `on_keys()`, `on_cmd()` and tracks loaded modules in `M._loaded`.
- **Mini.nvim monorepo**: Most UI/functionality comes from the single `mini.nvim` package. Its submodules (starter, pick, extra, files, icons, notify, cmdline, completion, snippets, diff, surround, ai, cursorword, pairs) are configured individually in `lua/pack.lua` or on-demand.
## File Loading Order
```
init.lua → disables ~20 built-in plugins, sets colorscheme, loads core modules
options.lua → global vim options, yank highlighting, fold settings
keymaps.lua → keymaps (leader = space)
autocmds.lua → cursor restore, comment continuation, fold setup
usercmds.lua → :PackAdd, :PackDel, :PackUpdate
pack.lua → plugin declarations + lazy-loading bindings
```
## Plugin Commands
```vim
:PackAdd user/repo " add plugin
:PackDel plugin-name " delete plugin
:PackUpdate [name] " update all or specific plugin
:ExColors! " extract current colorscheme to optimized ex-colors
```
## Validation & Debugging
```bash
# Syntax check init.lua (run from repo root)
nvim --headless -c 'lua dofile("init.lua")' -c 'qa!'
# Check a specific module
nvim --headless -c 'lua require("pack")' -c 'qa!'
# Health check
nvim --headless -c 'checkhealth' -c 'qa!'
# Measure startup time
nvim --startuptime /tmp/startup.log +q
```
There is no traditional lint, typecheck, or test command. The validation commands above are the only verification steps.
## Lazy-Loading Strategy
When adding new plugins that should load lazily, use the custom framework in `lua/lazy.lua` — do **not** use lazy.nvim patterns.
| Trigger | Plugins / Modules |
|---------------|--------------------------------------|
| `VimEnter` | treesitter, lsp, icons |
| `InsertEnter` | completion, snippets, pairs |
| `BufReadPost` | diff, surround, ai, cursorword |
| `BufWritePre` | conform (format-on-save) |
| Key press | pick, files, fugitive, grugfar |
| Command | ex-colors (`:ExColors`) |
## LSP & Formatting
- **LSP servers enabled**: html, cssls, gopls, vtsls, rust_analyzer, lua_ls, taplo, svelte, dartls, kotlin_lsp
- **Lua LSP**: `vim` is declared as a global in `lua_ls` settings to suppress "Undefined global" diagnostics
- **Formatters by filetype**:
- `lua` → stylua
- `go` → gofumpt, goimports
- `js/ts/json/css/html/md` → biome (if `biome.json` found) or prettier
- `toml` → taplo
- **Toggle autoformat**: `vim.b[bufnr].autoformat = false` (buffer) or `vim.g.autoformat = false` (global)
## Key Conventions
- Startup performance is a priority. Heavy modules are deferred to `VimEnter` or later. Clipboard is set via `vim.schedule()` to avoid blocking.
- The active colorscheme is `ex-catppuccin-mocha`, defined in `colors/ex-catppuccin-mocha.lua`.
- Comments and UI strings are in **Chinese**.

37
PLUGINS.md Normal file
View File

@ -0,0 +1,37 @@
# Plugins
本文件列出当前 Neovim 配置中使用的所有插件。
## 插件列表
### 核心插件
| 插件 | 仓库 | 用途 |
| --------------------- | ------------------------------------------------------------------------------------- | -------------------------------- |
| **mini.nvim** | [nvim-mini/mini.nvim](https://github.com/nvim-mini/mini.nvim) | 单体插件集,提供多种 UI/功能模块 |
| **nvim-treesitter** | [nvim-treesitter/nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) | 语法树解析与语法高亮 |
| **nvim-lspconfig** | [neovim/nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) | LSP 客户端预设配置 |
| **mason.nvim** | [mason-org/mason.nvim](https://github.com/mason-org/mason.nvim) | LSP/DAP/格式化工具安装管理 |
| **conform.nvim** | [stevearc/conform.nvim](https://github.com/stevearc/conform.nvim) | 代码格式化(保存时自动格式化) |
| **vim-fugitive** | [tpope/vim-fugitive](https://github.com/tpope/vim-fugitive) | Git 集成 |
| **grug-far.nvim** | [MagicDuck/grug-far.nvim](https://github.com/MagicDuck/grug-far.nvim) | 搜索与替换 |
| **friendly-snippets** | [rafamadriz/friendly-snippets](https://github.com/rafamadriz/friendly-snippets) | 社区代码片段集合 |
### mini.nvim 子模块
| 模块 | 用途 | 加载方式 |
| ------------------- | --------------------------------- | -------------------- |
| **mini.starter** | 启动页Neovim Logo + 启动耗时) | 直接加载 |
| **mini.files** | 悬浮文件浏览器 | 按键触发 (`-` / `_`) |
| **mini.icons** | 文件类型图标 | VimEnter 延迟加载 |
| **mini.notify** | 浮动通知消息 | 直接加载 |
| **mini.pairs** | 自动括号配对 | InsertEnter 懒加载 |
| **mini.ai** | 扩展 textobject函数、参数等 | BufReadPost 懒加载 |
| **mini.cursorword** | 自动高亮光标下相同单词 | BufReadPost 懒加载 |
| **mini.cmdline** | 增强命令行界面 | 首次按 `:` 触发 |
| **mini.pick** | 文件/内容查找器 | 按键触发 |
| **mini.extra** | pick 扩展keymaps、oldfiles 等) | 按键触发 |
| **mini.completion** | 自动补全引擎LSP + Buffer | InsertEnter 懒加载 |
| **mini.snippets** | 代码片段引擎 | InsertEnter 懒加载 |
| **mini.diff** | Git diff 标记signcolumn | BufReadPost 懒加载 |
| **mini.surround** | 环绕文本操作(括号、引号等) | BufReadPost 懒加载 |

View File

@ -6,7 +6,7 @@
- **内置插件管理器**`vim.pack`Neovim 0.12+),无需 lazy.nvim / packer
- **自定义懒加载框架**`lua/lazy.lua`(约 35 行),通过 `on_event` / `on_keys` / `load` 延迟加载重型模块
- **mini.nvim 单体插件集** — starter、pick、extra、files、icons、notify、cmdline、completion、snippets、diff、surround
- **mini.nvim 单体插件集** — starter、pick、extra、files、icons、notify、cmdline、completion、snippets、diff、surround、ai、cursorword、pairs
- **LSP + 代码格式化** — nvim-lspconfig + mason + conform.nvim保存时自动格式化支持全局/Buffer 级别开关
- **快速启动** — 禁用约 20 个内置插件,启用 Neovim 0.12+ 内置 UI 增强 (`vim._core.ui2`)
- **启动仪表盘** — ASCII Logo + 实时模块加载统计 + 启动耗时
@ -14,14 +14,15 @@
## 懒加载策略
| 触发条件 | 插件 |
| ------------- | ------------------------------ |
| `VimEnter` | treesitter、lsp、icons |
| `InsertEnter` | completion、snippets |
| `BufReadPost` | diff、surround |
| `BufWritePre` | conform |
| 按键触发 | pick、files、fugitive、grugfar |
| 命令触发 | ex-colors (`:ExColors`) |
| 触发条件 | 插件 |
| ------------- | --------------------------------------- |
| `VimEnter` | treesitter、lsp、icons |
| `InsertEnter` | completion、snippets、pairs |
| `BufReadPost` | diff、surround、ai、cursorword |
| `BufWritePre` | conform |
| 按键触发 | pick、files、fugitive、grugfar |
| 首次按 `:` | cmdline |
| 命令触发 | ex-colors (`:ExColors`) |
## 键位映射
@ -30,3 +31,7 @@
## 开发与调试
开发相关的命令、健康检查、性能测量等见 [DEVELOPMENT.md](./DEVELOPMENT.md)。
## Plugins
[PLUGINS](./PLUGINS.md)