plannotator/herdr-annotate

Annotate terminal text, review documents and agent replies in Herdr, and send the feedback straight back to the agent.

herdr‑annotate 是什么？

herdf‑annotate 是 Herdr 终端/AI代理环境的一个 基于 Rust 的插件。它让你能够：

选择任何终端输出，并将其转换为可发送到当前 LLM 代理的带编号的 Markdown 注释。
在配套项目 plannotator‑tui 驱动的 TUI 中，查看整个 Markdown 文档或代理之前的回复。
在 Herdr 内直接管理、复制、存档或粘贴这些注释到代理的提示中。

简而言之，它弥合了你在终端中看到的原始文本与 LLM 驱动的助手反馈循环之间的差距。

主要功能

功能	描述
完整版与精简版安装	完整版增加了文档查看界面；精简版仅提供终端文本注释。
键盘驱动的工作流	像 `prefix+a`（捕获）、`prefix+ctrl+s`（发送并存档）、`prefix+o`（打开文件夹查看）这样的绑定让你留在终端里。
Markdown 反馈格式	注释以 `## Annotation N` 块的形式输出，包含工作区/标签元数据和引用的源文本，可随时供 LLM 使用。
剪贴板感知	在 macOS/Linux 上使用系统剪贴板（`wl‑clipboard`、`xclip`、`xsel`），在 Windows 上使用 PowerShell；同时为远程会话输出 OSC 52。
代理无关	与 Claude Code、Codex、pi、Copilot CLI、Droid、Hermes CLI、OpenCode 等兼容。
远程会话支持	可通过 SSH 或 `herdr --remote` 调用，无需本地按键，调用 `herdr plugin action invoke annotate.capture` 即可。
链接附加组件	可选附加组件，使 `Ctrl-click` 点击 `file://*.md` 链接可在 plannotator‑tui 查看器中打开。
跨平台	macOS、Linux、Windows（完整版为预览版）。

安装

# 完整安装（默认）– 包含文档查看界面
herdr plugin install plannotator/herdr-annotate

# 精简安装 – 仅终端注释
herdr plugin install plannotator/herdr-annotate/lite

# Windows 完整版（预览）– 需要 Herdr ≥ 0.9.0
herdr plugin install plannotator/herdr-annotate/windows-full

该命令下载预构建的 herdr-annotate 二进制文件，验证其 SHA‑256 校验和，并将其注册为 Herdr 插件。无需额外运行时。

基本用法（完整安装）

按键	操作
`prefix+a`	将选定的终端文本捕获为注释。
`prefix+shift+a`	将所有注释（Markdown）复制到剪贴板。
`prefix+ctrl+a`	复制并存档所有注释。
`prefix+ctrl+v`	将注释粘贴到聚焦的代理提示中（不发送）。
`prefix+ctrl+s`	将注释作为下一条代理消息发送并存档。
`prefix+m`	打开注释管理器（列表、复制、存档、删除）。
`prefix+o`	打开文件夹范围的文档查看器（plannotator‑tui）。
`prefix+shift+o`	查看代理最近的回复。
`prefix+ctrl+o`	查看最新回复，无需选择器。

管理器窗格按创建顺序显示注释，因此 LLM 会按顺序接收反馈。

文档查看（完整安装）

按 prefix+o 启动当前文件夹的文件树视图。
使用 prefix+shift+o 或 prefix+ctrl+o 浏览最近的代理回复。
在 TUI 中，你可以编辑、评论，并将查看结果发送回代理（E 发送，q 退出）。
安装可选的 Links 附加组件，使 Ctrl-click 点击 file://*.md 链接直接在查看器中打开：
```
herdr plugin install plannotator/herdr-annotate/links
```

远程 / SSH 工作流

在服务器上保留选择：在服务器的 ~/.config/herdr/config.toml 中设置 copy_on_select = false。

从本地机器调用捕获操作，无需按键：

ssh host herdr plugin action invoke annotate.capture

插件通过 Herdr API 读取选择内容，从而无需本地剪贴板。

开发与扩展

插件位于 rust/ 中，使用 Cargo 构建。

典型的开发周期：

cargo test --manifest-path rust/Cargo.toml
cargo clippy --manifest-path rust/Cargo.toml -- -D warnings
bash scripts/stage-local.sh   # 构建并暂存二进制文件
herdr plugin link $PWD        # 链接以进行本地测试

你可以通过链接相应的目录在精简版和完整版之间切换。
Links 附加组件没有编译的组件；它仅注册一个插件，将 file:// 点击转发到完整版二进制文件。

谁应该使用这个？

使用 LLM 的开发者，他们在终端中工作，希望快速注释代码输出、错误消息或日志，并将其反馈给助手。
研究人员，正在迭代提示工程；管理器让他们存档和重放过去的反馈。
团队，使用 Herdr 作为共享 AI 助手界面，并需要跨会话一致的注释格式。

快速参考速查表

# 示例键绑定（放置在 ~/.config/herdr/config.toml 中）
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "annotate.capture"
description = "annotate text"

# … 按 README 的指示添加其余部分 …

总之： herdr‑annotate 将终端选择转换为结构化的、LLM 可用的反馈，并让你查看整个文档——全程无需离开 Herdr 环境。