herdr-annotate × Neovim:基于文件交接选区的完整集成指南

原创2026-11-01 10:20:52515 阅读

herdr-annotate × Neovim:基于文件交接选区的完整集成指南

herdr-annotate 是一个面向终端会话 Herdr 的批注插件:在任意终端文本上添加注释、评审文档与 agent 回复,并把反馈直接发回给 AI agent。它与 Neovim 配合时最大的坑是"选区传不过去"——插件无法读取 Neovim 的选区状态。本文用官方内置的**文件交接(file handoff)**机制一次打通:不依赖剪贴板,远程服务器同样可用。

herdr-annotate Neovim 文件交接选区集成总览

为什么 Neovim 选区要靠"文件交接"传递

herdr-annotate 的设计是从系统剪贴板读取选中文字,插件本身读不到 Neovim 或其他终端应用内部的选区状态(详见 README - Selection limits)。以下两个场景里,剪贴板链路会彻底失效:

  1. 远程 / 无头服务器:SSH 服务器上没有任何剪贴板工具,插件无剪贴板可回退;
  2. 按键副作用:远程会话中 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" })

它按顺序做四件事:

  1. normal! "zy:把当前可视选区拷入 z 寄存器(不影响其他寄存器);
  2. 拼出交接目录 herdr-annotate-<uid> 并创建(权限 0700,仅当前用户可读写);
  3. 把选区文本写入 selection 文件;
  4. 用 jobstart 异步触发 herdr plugin action invoke annotate.capture,插件捡起文件并弹出批注编辑器。

Neovim 端拼出的目录结构与插件端 handoff_path() 完全一致,保证两端读写同一个位置。LazyVim 默认 <leader> 是 Space,所以快捷键就是 V 选中文本后按 Space a。映射只注册在可视模式,不会改动你现有的任何 Neovim 命令。

使用流程:从选中文本到反馈发给 agent

集成完成后的日常操作只有四步:

  1. 在 Neovim(或鼠标)选住要批注的文本;
  2. 按 <leader>a → 弹出 herdr-annotate 批注编辑器,选区已预填;
  3. 输入批注意见,Ctrl+S 保存;
  4. 把反馈交给 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。

登录后查看全文
herdr-annotate