herdr-annotate × Neovim:基于文件交接选区的完整集成指南
herdr-annotate × Neovim:基于文件交接选区的完整集成指南
herdr-annotate 是一个面向终端会话 Herdr 的批注插件:在任意终端文本上添加注释、评审文档与 agent 回复,并把反馈直接发回给 AI agent。它与 Neovim 配合时最大的坑是"选区传不过去"——插件无法读取 Neovim 的选区状态。本文用官方内置的**文件交接(file handoff)**机制一次打通:不依赖剪贴板,远程服务器同样可用。
为什么 Neovim 选区要靠"文件交接"传递
herdr-annotate 的设计是从系统剪贴板读取选中文字,插件本身读不到 Neovim 或其他终端应用内部的选区状态(详见 README - Selection limits)。以下两个场景里,剪贴板链路会彻底失效:
- 远程 / 无头服务器:SSH 服务器上没有任何剪贴板工具,插件无剪贴板可回退;
- 按键副作用:远程会话中 Herdr 的"选中即复制"默认行为与 prefix 按键都会先清掉选区,动作执行时选区已经没了。
官方给出的解法就是文件交接:由 Neovim 把选区文本写进一个临时文件,再触发批注动作,插件直接读文件。不碰剪贴板、不碰键盘路径,一次写入、一次交接。
文件交接机制解析:路径规则 + 15 秒时效 + 即读即删
插件的 capture 动作内部有三级文本来源回退(见 rust/src/cli.rs):
| 优先级 | 文本来源 | 适用场景 |
|---|---|---|
| 1 | Herdr 调用上下文里的选区 | 直接在 Herdr 面板内选中文本 |
| 2 | 交接文件 | Neovim 等编辑器交接(本文主角) |
| 3 | 系统剪贴板 | 前两者都没有时的兜底 |
交接文件规则定义在 rust/src/handoff.rs,记住三点:
- 路径:
$XDG_RUNTIME_DIR/herdr-annotate-<uid>/selection;未设置XDG_RUNTIME_DIR时回退到系统临时目录。按用户 uid 分目录,互不串扰; - 时效:文件修改时间超过 15 秒即视为过期,直接忽略,防止捡到旧选区;
- 即读即删:无论新鲜还是过期,文件都会被读取(若可用)后自动删除,无需手动清理。
一键安装 herdr-annotate:两条命令搞定
要求 Herdr 0.8.0 及以上,支持 macOS / Linux / Windows。无需安装任何运行时——插件在构建时下载预编译二进制并校验 SHA-256:
herdr plugin install plannotator/herdr-annotate
这是 Full 版(终端批注 + 文档评审 + agent 回复评审)。如果只需要"选中文本加批注",可换成 Lite 版:
herdr plugin install plannotator/herdr-annotate/lite
提示:Linux 本地使用剪贴板兜底路径时需安装
wl-clipboard、xclip或xsel之一;纯远程场景只走文件交接,可不装。
配置 Herdr 快捷键并加载生效
在 Herdr 配置文件中加入以下绑定(本文用到的最小集):
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "annotate.capture"
description = "annotate text"
[[keys.command]]
key = "prefix+m"
type = "plugin_action"
command = "annotate.manage"
description = "manage annotations"
然后校验并重载配置:
herdr config check
herdr server reload-config
全部可用动作(capture、copy-context、paste-archive、send-archive、manage 等)都声明在插件清单 herdr-plugin.toml 中,可按需自行绑定。
Neovim 选区映射配置:LazyVim 与 init.lua 两种放法
下面这段是官方提供的 Neovim 映射。LazyVim 用户放入 ~/.config/nvim/lua/config/keymaps.lua,原生配置放入 init.lua:
vim.keymap.set("x", "<leader>a", function()
vim.cmd('normal! "zy')
local base = os.getenv("XDG_RUNTIME_DIR")
if not base or base == "" then base = vim.fn.fnamemodify(vim.fn.tempname(), ":h") end
local dir = base .. "/herdr-annotate-" .. vim.loop.getuid()
vim.fn.mkdir(dir, "p", "0700")
vim.fn.writefile(vim.split(vim.fn.getreg("z"), "\n"), dir .. "/selection")
vim.fn.jobstart({ "herdr", "plugin", "action", "invoke", "annotate.capture" })
end, { desc = "Annotate in Herdr" })
它按顺序做四件事:
normal! "zy:把当前可视选区拷入z寄存器(不影响其他寄存器);- 拼出交接目录
herdr-annotate-<uid>并创建(权限0700,仅当前用户可读写); - 把选区文本写入
selection文件; - 用
jobstart异步触发herdr plugin action invoke annotate.capture,插件捡起文件并弹出批注编辑器。
Neovim 端拼出的目录结构与插件端 handoff_path() 完全一致,保证两端读写同一个位置。LazyVim 默认 <leader> 是 Space,所以快捷键就是 V 选中文本后按 Space a。映射只注册在可视模式,不会改动你现有的任何 Neovim 命令。
使用流程:从选中文本到反馈发给 agent
集成完成后的日常操作只有四步:
- 在 Neovim(或鼠标)选住要批注的文本;
- 按
<leader>a→ 弹出 herdr-annotate 批注编辑器,选区已预填; - 输入批注意见,
Ctrl+S保存; - 把反馈交给 agent:
Ctrl+B Ctrl+V:把全部批注以 Markdown 粘贴进当前面板 agent 的输入框(不发送,还能继续编辑);Ctrl+B Ctrl+S:直接作为 agent 的下一条消息发送。
批注会按你书写的先后顺序、最旧的优先交接,agent 读反馈的顺序与你走读文本的顺序一致。Ctrl+B M 打开管理面板,可编辑(e)、复制、归档、删除批注。
SSH 远程会话的特殊配置
文件交接在无头服务器上天然可用,但远程场景还有两处要微调(详见 README - Remote sessions):
1. 服务器端保留选区(服务器上 ~/.config/herdr/config.toml):
[ui]
copy_on_select = false # 选中后不自动复制,选区得以保留
2. 让服务器端按键绑定生效,否则 herdr --remote 会沿用本地按键、丢掉插件绑定:
herdr --remote <host> --remote-keybindings server
备选方案:在本地选完文本后,直接在终端执行
ssh <host> herdr plugin action invoke annotate.capture
它通过 Herdr API 读取选区,完全绕开键盘路径。
常见问题:Nothing to annotate 怎么排查
按下快捷键却只看到 Nothing to annotate 提示(对应 rust/src/cli.rs 的空选区检查),按此顺序排查:
| 现象 | 原因 | 解决 |
|---|---|---|
| 文件写了但没被读到 | Neovim 与插件进程的 XDG_RUNTIME_DIR 不一致(例如 Neovim 从桌面环境启动) |
让两端使用同一环境变量,或都不设置、统一回退系统临时目录 |
| 文件未被采用 | 文件超过 15 秒时效 | 映射是"写文件 + 触发动作"一气呵成,正常不会触发;手动 touch 调试则会超时 |
| 选了空白内容 | 空白文本按设计被忽略 | 选中实际内容再试 |
另外记住:交接文件被读取后会自动删除。如果发现文件残留,说明动作没有执行成功,通常是 herdr CLI 不在 PATH 里。
写在最后
herdr-annotate × Neovim 集成的核心一句话:把剪贴板问题变成文件问题。
- 📦 选区走临时文件交接:15 秒时效、单次读取、自动清理;
- 🔧 两条命令安装 + 一段 Lua 映射完成集成,零额外依赖;
- 🌐 本地与 SSH 远程 / 无头场景通吃,批注以标准 Markdown 格式直接送达 agent。
延伸阅读:README.md 的 Neovim integration 与 Remote sessions 章节,以及 Lite 版回归测试说明 docs/lite-testing.md。
