# 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`