# nvim-frame **Repository Path**: cjl2385/nvim-frame ## Basic Information - **Project Name**: nvim-frame - **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-16 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # nvim-frame > 把 Neovim 实际绘制的画面转成帧 JSON、文本、ANSI、HTML、SVG 和 PNG,既是给 AI agent 用的 skill,也是零依赖的小型库

English | 中文

nvim-frame 启动一个隔离的 `nvim --embed`,通过 UI 协议还原屏幕(真彩色、宽字符、浮窗、虚拟文本),输出规范化的帧。同样的屏幕得到逐字节相同的输出 ## 能做什么 - 让 agent 看到真实画面:验证配置、插件界面、浮窗、高亮、statusline、cmdline - 给文档和页面生成 Neovim 截图,或逐步演示按键效果 - 把你的配置在隔离副本里跑一遍,看实际画面 ## 作为 AI agent 的 skill 安装 ```bash npx skills add https://gitee.com/cjl2385/nvim-frame.git --skill nvim-frame ``` 本地验证:在临时工作区里执行 `npx skills add /absolute/path/to/nvim-frame --skill nvim-frame`。请用仓库的真实绝对路径,不要用指向工作区的 `.`;安装只作用于当前项目,且不会覆盖已有的 skill 安装后,agent 会自行判断何时使用:需要看到配置、插件界面、浮窗、高亮、statusline 或 cmdline 的真实画面,或要为文档、页面生成 Neovim 截图、逐步演示按键效果时。它会读取 `SKILL.md`,并调用随附的命令行 `/scripts/nvim-frame.mjs` 兼容性:可在 Node.js 22+ 或 Bun ≥ 1.2 上运行,零运行时依赖。PNG 需要本机 Chrome / Chromium / Edge;`copy` 配置模式不依赖外部命令,网络隔离只在 macOS 上用 `sandbox-exec`,其他平台仅把代理指向死端口 ## 更新 skill 检查更新,或只更新已全局安装的这一个 skill: ```bash npx skills check npx skills update nvim-frame -g ``` **只覆盖 Claude Code 全局目录** ```bash npx skills add https://gitee.com/cjl2385/nvim-frame.git --skill nvim-frame --agent claude-code --global --copy --yes ``` **开发本仓库时**:`bun run sync:skill` 会把工作副本原子替换到 `~/.claude/skills/nvim-frame`,无需发布即可验证改动 ## 命令行 `` 是已安装的 skill 目录,bun 与 node 输出一致: ```bash # 执行 Lua,再按键,输出纯文本 bun "/scripts/nvim-frame.mjs" run --lua 'vim.o.number = true' --keys 'ihello' --format text # 按 Lua 文件里的 "-- @step" 逐步取帧并输出 PNG(没有 Chrome 时用 --format svg) bun "/scripts/nvim-frame.mjs" run demo.lua --steps --format png --frame last --out demo.png # 给程序用的 JSON,给页面用的静态片段 bun "/scripts/nvim-frame.mjs" run demo.lua --steps --format json --out demo.json bun "/scripts/nvim-frame.mjs" run demo.lua --steps --format fragment --out frames.html ``` `--format` 可选 `json`(默认)、`text`、`ansi`、`html`、`fragment`、`svg`、`png`;`--config` 可选 `clean`(默认)、`init:`、`copy[:]`。退出码:0 成功,1 Lua 报错、超时或 nvim 与浏览器不可用,2 用法错误。`help` 列出全部选项,`skills/nvim-frame/assets/example.lua` 是现成的示例 ## 库 API 入口 `skills/nvim-frame/scripts/lib/index.mjs` | 导出 | 用途 | | --- | --- | | `run(input, opts)` | 执行 Lua 与按键,返回帧 | | `NvimSession.start(opts)` | 长会话 | | `toText` `toAnsi` `toHtml` `toPage` `toSvg` `toPng` | 各格式渲染 | | `createPngRenderer` | 复用一个浏览器批量出 PNG | | `stable(result)` `sortKeys(value)` | 去掉耗时字段,便于 diff | | `parseSize` `findBrowser` | 辅助函数 | 细节见 `skills/nvim-frame/SKILL.md` 与 `skills/nvim-frame/references/`(`lua.md`、`schema.md`、`embed.md`) ## 依赖 - Neovim 0.12+(已测 0.12.6 与 0.13-dev;更早版本没有 `nvim__redraw` 时走降级路径,未实测) - Node.js 22+ 或 Bun 1.2+,零运行时依赖 - PNG 输出需要本机 Chrome / Chromium / Edge - `copy` 配置模式不依赖外部命令;禁止外连只在 macOS 上靠 `sandbox-exec` ## 开发与测试 ```bash mise install # neovim 0.12.6,快照依赖这个版本 bun run test # bun test --timeout 60000 test/ bun run format:check # dprint bun run playground # http://127.0.0.1:5177 ``` - 测试用的 nvim 依次取 `NVIM_FRAME_TEST_NVIM`、`mise which nvim`、PATH 上的 `nvim`;快照只在 0.12.6 上比对 - `UPDATE_SNAPSHOTS=1 bun run test` 重写快照,先确认差异合理 - tmux 对照测试需要 `tmux`,PNG 测试需要 Chrome,缺失时自动跳过 - `playground/` 是本地试玩页:改 Lua 和按键,一次看到所有输出格式(预览、文本、ANSI、HTML、SVG、PNG、JSON)。它会执行你输入的 Lua,所以默认只监听 `127.0.0.1`、校验 Host 与 Origin、只用 `clean` 配置;不随 skill 分发,PNG 需要 Chrome - 局域网访问:`bun run playground -- --host 0.0.0.0` 会打印带随机访问令牌的链接(首次访问后换成 cookie)。Lua 能执行 shell 命令,拿到链接的人等同于以你的身份操作,且链接是明文 HTTP;只在可信网络使用 ## 许可 [MIT](LICENSE)。内置的 Nerd Fonts 符号字体沿用 `skills/nvim-frame/assets/fonts/LICENSE`