# learn-nvim **Repository Path**: cjl2385/learn-nvim ## Basic Information - **Project Name**: learn-nvim - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-15 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # learn-nvim 写给前端开发者(TS / React / Vue)的 Neovim 课程,配一套可交互的 API 手册。和 learn-go、learn-rust 同构。页面里的每段 Lua 都在真实的 Neovim 0.12.6 里运行,页面把运行后的屏幕画出来,可以逐步播放,也可以改代码或直接敲键盘 ## 依赖 lab 的引擎是 [**nvim-frame**](https://gitee.com/cjl2385/nvim-frame) skill 的核心库(UI 协议、屏幕网格、帧 schema、配置副本都在那里实现,本仓库不复制它的代码)。需要: - nvim-frame skill 安装在 `~/.claude/skills/nvim-frame/`(需要 `scripts/lib/index.mjs` 与 `assets/nvim-live-lib.tsx`): ```bash npx skills add https://gitee.com/cjl2385/nvim-frame.git --skill nvim-frame --agent claude-code --global --copy --yes ``` - 装在别处(或直接用 nvim-frame 仓库的工作副本)时,设环境变量 `NVIM_FRAME_LIB` 指向它的 `scripts/lib/index.mjs`,例如 `NVIM_FRAME_LIB=/path/to/nvim-frame/skills/nvim-frame/scripts/lib/index.mjs bun run lab` - 库缺失时 `bun run lab`、`bun test`、渲染脚本都会立即报 `lab: nvim-frame library not found: <路径>` 并退出,不会半途出错 - 帧格式就是 skill 的 schema v1(`references/schema.md`),升级 skill 时如果 schema 版本变了,重新 `UPDATE_SNAPSHOTS=1 bun test` 并看 diff ## 开始 ```bash mise install # 按 mise.toml 安装固定版本的 neovim 0.12.6 bun run lab # 打开 http://127.0.0.1:8083 LAB_ADDR=<网卡地址>:8083 bun run lab # 远程访问(如 WireGuard)时绑定到对应网卡地址,也可用 --addr ``` 整个项目只需要启动这一个服务,lab 同时托管页面和演示接口。直接双击 HTML 也能读,演示区显示快照(图标字体与页面内按键操作需要 lab) ## 目录 ``` learn-nvim/ ├── index.html # 导航:课程 / API 手册 / 附录 ├── mise.toml # 固定 neovim 0.12.6,快照依赖这个版本 ├── package.json # bun 脚本,零运行时依赖 ├── lab/ # 本地服务:静态页面 + 演示接口 + /api/run + /api/nvim/input │ ├── main.ts, src/ # 服务、接口层、脱敏、会话管理、快照、版本检查;UI 协议与配置副本来自 nvim-frame(frame-lib.ts 是唯一入口) │ ├── lua/harness.lua # 在被测 nvim 里运行:@step / @show / @wait / 行尾 `-- →`,注入 nvim-frame 的 run() │ ├── live-lib/ # 页面组件(StepPlayer 等),渲染时与 skill 的 nvim-live-lib.tsx 合并注入页面 │ ├── fonts/ # Symbols Nerd Font Mono(woff2),见下 │ └── tests/ # bun 测试 ├── lessons/ # 课程:源稿、HTML、demos(Lua + 快照)、excerpts ├── reference/ # API 手册:源稿、entries.ts、snapshots.json ├── appendix/ # 附录 ├── scripts/ # render.ts、check-docs.ts、probe.ts、ttf2woff2.ts └── STYLE.md # 写作与制作规范(含并行写作的开工清单) ``` ## 环境 - bun 与 mise。nvim 由 `mise.toml` 固定为 0.12.6,lab 启动时用 `mise which nvim` 解析出绝对路径,不依赖 PATH 上的 nvim;也可用 `LAB_NVIM` 指定。版本与 `mise.toml` 不一致时 lab 启动会警告,快照测试直接失败 - 重新渲染页面需要 answer-with-html skill,步骤见 `STYLE.md` 第 9 节 - 常用:`bun test`(全部测试)、`UPDATE_SNAPSHOTS=1 bun test`(回填快照)、`LAB_TEST_USER=1 bun test lab/tests/user.test.ts`(「你的配置」模式,依赖本机配置) - 环境变量:`LAB_ADDR`、`LAB_NVIM`、`LAB_TMP`(临时目录根,默认 `$TMPDIR/learn-nvim`)、`LAB_USER_CONFIG=0`(关闭「你的配置」)、`LAB_USER_NVIM` / `LAB_USER_NVIM_DATA`(user 模式的配置与 data 源目录,默认 XDG 位置)、`LAB_CONCURRENCY`、`LAB_MAX_SESSIONS`、`NVIM_FRAME_LIB`(见「依赖」)、`NVIM_FRAME_SANDBOX=0`(user 模式不用 sandbox-exec,由 skill 读取) - 字体:`lab/fonts/SymbolsNerdFontMono-Regular.woff2` 来自 Nerd Fonts v3.5.1 的 `NerdFontsSymbolsOnly.zip`(),许可为 MIT(`lab/fonts/LICENSE-NerdFonts.txt`,其中的符号来自各自许可的图标集)。TTF 用 `scripts/ttf2woff2.ts` 转换(只做 brotli 压缩) ## 关于 lab 与「你的配置」 lab 会在本机执行读者提交的 Lua,Lua 能运行任意命令,只用于本地学习,**不是沙箱**。默认只监听 127.0.0.1。设置 `LAB_ADDR` 对外监听时,同一网络里的设备都能通过它以你的用户权限执行代码,只在可信网络里这样用 具体做了什么限制,以及没有做什么: - 每个请求一个独立的 `nvim --embed -n -i NONE --clean`,`NVIM_APPNAME=nvim-frame`;HOME、XDG 目录与 TMPDIR 都在临时目录(`$TMPDIR/learn-nvim/nvim-frame-XXXXXX`)里,结束后删除;环境变量只留固定的 PATH、HOME、LANG 与这些目录 - 代码最大 64 KiB,总时限 10 秒(从 nvim 进程启动后算起,超时杀进程组),一次性请求并发 3 个其余排队,页面内按键会话 4 个(空闲 2 分钟或存活 10 分钟回收) - 返回给页面的所有文本与屏幕都做了脱敏:临时目录、HOME、仓库路径、nvim 安装路径、`/Users/<名>`、`/home/<名>`、用户名 - 没有做:文件系统、进程、网络隔离。`--clean` 模式下 Lua 仍然可以读写你的文件、联网 - 「你的配置」模式(`config: 'user'`)加载 `~/.config/nvim` 与 data 里插件的临时副本,原目录只读;插件联网被代理黑洞与 macOS 的 `sandbox-exec` 拦住。细节与已知副作用见 `STYLE.md` 第 8 节,实现是 nvim-frame 的 copy 模式(`lab/src/nvim-opts.ts` 只决定拷哪些目录)。副本底稿缓存在 `.cache/nvim-frame/`(已被 `.gitignore` 忽略) ## 课程地图 课程、手册、附录的完整地图、写作规范与并行写作清单见 `STYLE.md` ## 许可 - 课程正文、代码与 lab:MIT,见 `LICENSE` - 依赖的 [nvim-frame](https://gitee.com/cjl2385/nvim-frame) 不随本仓库分发,许可见其仓库(MIT) - `lab/fonts/SymbolsNerdFontMono-Regular.woff2`:Nerd Fonts,MIT,见 `lab/fonts/LICENSE-NerdFonts.txt`(其中的符号来自各自许可的图标集) - `lessons/20-read-a-plugin/fixture/` 里的 vv-hover.nvim、vv-utils.nvim 部分源码副本:MIT,许可证随副本放在各自目录