这是一个基于 lazy.nvim 的模块化 Neovim 配置，目标是提供轻量、清晰、接近 IDE 的 Go / Python / Lua / Shell / Markdown 开发体验。

本节由原 AGENTS.md 迁移并补充，作为人类读者和编码代理都可参考的配置总览。

• 入口文件：init.lua
• 插件管理器：folke/lazy.nvim
• Leader 键：<Space>
• 主题：catppuccin/nvim，默认 catppuccin-mocha
• LSP：gopls、pyright、lua_ls、clangd
• 主要功能：文件浏览器、Telescope 搜索、LSP、补全、格式化、Lint、Git hunk、诊断面板、任务运行、Session 恢复、浮动终端、Markdown 渲染、快捷键提示

• mini.files：浮动文件浏览器
• mini.jump：扩展 f / F / t / T 在多行工作
• mini.jump2d：可见行内的迭代标签跳转
• floaterm：浮动终端；进入浮动终端后预留 Ctrl+l/a/e/k 给 shell 使用
• nvim-lspconfig：LSP 配置
• formatter.nvim：格式化
• Comment.nvim：注释
• render-markdown.nvim：Markdown 渲染
• markdown-preview.nvim：Markdown 浏览器预览（含 Mermaid 支持）
• LspUI.nvim：LSP UI 增强
• barbar.nvim：Buffer 标签栏
• telescope.nvim：搜索 / Picker
• gitsigns.nvim：Git hunk / blame
• nvim-lint：异步 lint
• trouble.nvim：诊断 / quickfix / LSP 列表
• nvim-autopairs：自动括号
• overseer.nvim：任务运行器
• nvim-surround：Surround 操作
• indent-blankline.nvim：缩进线
• dropbar.nvim：winbar 面包屑（LSP / Treesitter / Path 自动 fallback）
• auto-session：Session 管理
• pi.nvim：Neovim 内通过 pi CLI 与 AI 交互

• Neovim >= 0.12，当前配置使用了新版 vim.lsp.config() / vim.lsp.enable() API
• Git >= 2.19
• 推荐安装 Nerd Font，保证图标显示正常
• 推荐命令行工具：
  • rg：Telescope 全文搜索
  • fd：Telescope 文件查找体验更好
  • tree-sitter：Treesitter parser 安装与更新

init.lua
lua/
  core/
    options.lua      # 基础选项、诊断显示配置
    keymaps.lua      # 全局快捷键
    autocmds.lua     # 自动命令、LSP 快捷键、自动保存
  plugins/
    completion.lua   # nvim-cmp / LuaSnip 补全
    diagnostics.lua  # nvim-lint / trouble.nvim
    editing.lua      # autopairs / surround / indent guides
    editor.lua       # 文件浏览器、注释、终端、buffer、treesitter、markdown、跳转
    formatter.lua    # formatter.nvim / mason-tool-installer
    git.lua          # gitsigns.nvim
    go.lua           # go.nvim (Go 开发)
    lsp.lua          # mason / lspconfig / LspUI
    session.lua      # auto-session
    tasks.lua        # overseer.nvim
    telescope.lua    # Telescope 搜索
    ui.lua           # 主题、通知、Noice UI、which-key
    pi.lua           # pi.nvim AI 交互
lazy-lock.json       # lazy.nvim 插件锁定文件

• 插件管理：folke/lazy.nvim
• 主题：catppuccin/nvim，默认 catppuccin-mocha
• UI：noice.nvim、nvim-notify、barbar.nvim、which-key.nvim

• LSP：nvim-lspconfig、mason.nvim、mason-lspconfig.nvim
• LSP UI：jinzhongjia/LspUI.nvim
• Go 开发：ray-x/go.nvim（gopls 管理、测试、格式化、代码生成、Tag 管理等）
• 补全：nvim-cmp、cmp-nvim-lsp、cmp-buffer、cmp-path
• Snippet：LuaSnip、friendly-snippets
• 格式化：formatter.nvim
• 工具安装：mason-tool-installer.nvim

默认 LSP：

• gopls（由 go.nvim 管理）
• pyright
• lua_ls
• clangd（C / C++ / Objective-C / CUDA）

默认格式化工具：

• Lua：stylua
• Python：black
• Go：gofumpt（通过 formatter.nvim，手动触发）
• Shell：shfmt
• C / C++ / Objective-C / CUDA：clang-format（通过 formatter.nvim；本配置根目录附带 LLVM 风格 .clang-format，各项目可自带规则覆盖）
• JS / TS / JSON / CSS / HTML / Markdown / YAML：prettier

已配置：

• Go：ray-x/go.nvim（gopls、测试、覆盖率、代码生成、Tag、文档、DAP 调试）
• Git：lewis6991/gitsigns.nvim
• Lint：mfussenegger/nvim-lint
• 诊断面板：folke/trouble.nvim
• 自动括号：windwp/nvim-autopairs
• 任务运行器：stevearc/overseer.nvim
• Surround 操作：kylechui/nvim-surround
• 缩进线：lukas-reineke/indent-blankline.nvim
• Session 管理：rmagatti/auto-session
• 快捷键提示：folke/which-key.nvim
• 跳转：nvim-mini/mini.jump（多行 f/F/t/T）、nvim-mini/mini.jump2d（可见区迭代跳转）

mason-tool-installer 同时补充安装常用 lint 工具：

• ruff
• golangci-lint
• shellcheck
• eslint_d
• markdownlint-cli2
• yamllint
• actionlint

Leader 键：<Space>

前缀键：<leader>G

常用命令：

:GoRun              " 运行当前文件
:GoTest             " 运行测试
:GoTestFunc         " 测试当前函数
:GoCoverage         " 测试覆盖率
:GoAlt              " 切换测试/实现文件
:GoDoc              " 查看文档
:GoImpl             " 实现接口
:GoIfErr            " 自动填充 if err
:GoModTidy          " mod tidy
:GoLint             " golangci-lint

Go 文件使用 <leader>fm 或 :Format 手动触发 gofumpt 格式化（已禁用保存时自动格式化）。

常用命令：

:OverseerRun
:OverseerShell
:OverseerToggle
:OverseerTaskAction

自定义任务模板：

• Go: Go: Run Current File / Go: Build Project（自动查找 go.mod）
• Flutter (fvm): Flutter: Run / Flutter: Build（支持选择构建目标）
• Docker: Docker: Compose Up / Docker: Compose Down（自动查找 compose 文件）

### Session / Auto Session

| 快捷键       | 功能                  |
| ------------ | --------------------- |
| `<leader>sr` | 恢复当前目录 Session  |
| `<leader>ss` | 保存当前目录 Session  |
| `<leader>sf` | 查找 Session          |
| `<leader>sd` | 删除当前目录 Session  |
| `<leader>sD` | 选择并删除 Session    |
| `<leader>st` | 切换 Session 自动保存 |
| `<leader>sp` | 清理孤立 Session      |

Session 会自动保存 / 恢复当前工作目录状态，并排除 `~/`、`~/Downloads`、`/` 等目录，避免在过大的根目录生成无意义 Session。
### Markdown 预览

| 快捷键        | 功能                   |
| ------------- | ---------------------- |
| `<leader>mps` | Markdown: 开始预览     |
| `<leader>mpS` | Markdown: 停止预览     |
| `<leader>mpr` | Markdown: 刷新预览     |

常用命令：

```vim
:MarkdownPreview       " 开始浏览器预览
:MarkdownPreviewStop   " 停止预览
:MarkdownPreviewRefresh " 强制刷新

Mermaid 图表在浏览器中渲染为可交互 SVG，支持缩放、平移和导出。

• which-key.nvim：按下 <leader> 等前缀键后显示可用快捷键；<leader>? 可查看当前 Buffer 的快捷键
• nvim-autopairs：Insert 模式自动补全括号、引号等，并集成 nvim-cmp 确认补全后的括号处理
• nvim-surround：使用默认快捷键，例如：
  • ys{motion}{char} 添加 surround
  • ds{char} 删除 surround
  • cs{old}{new} 修改 surround
• indent-blankline.nvim：显示缩进参考线和当前作用域

nvim-lint 会在以下事件触发：

• BufWritePost
• BufReadPost
• InsertLeave

已配置 filetype：

配置会在运行 lint 前检查 linter 可执行文件是否存在，避免缺少工具时反复报错。

:Lazy              " 插件管理 UI
:Lazy sync         " 同步/安装/清理插件
:Mason             " 管理 LSP、formatter、linter 等工具
:LspInfo           " 查看 LSP 状态
:checkhealth       " 检查 Neovim 健康状态
:Format            " 格式化当前文件
:Trouble diagnostics toggle
:OverseerRun
:AutoSession search
:WhichKey

• 当前配置开启了自动保存：编辑后延迟写入文件，并在离开 buffer / 失焦 / 退出前保存。
• lazy-lock.json 会锁定插件版本，便于复现环境。
• 如果新增语言支持，通常需要同时补充：LSP、formatter、linter、treesitter parser。