如何 3 分钟装好 herdr-file-viewer:从插件安装、按键召唤到渲染器配置的新手快速上手教程

原创2026-11-01 09:19:271,413 阅读

如何 3 分钟装好 herdr-file-viewer:从插件安装、按键召唤到渲染器配置的新手快速上手教程

herdr-file-viewer 是一个为 herdr 打造的 git 感知、只读终端文件查看器(file viewer):左侧是带 Git 状态标记的目录树,右侧自动给出文件最合适的视图——有改动就显示 diff,Markdown 直接渲染,代码则带语法高亮。全文键盘驱动、鼠标可选,且永不修改你的文件。本文带你从插件安装、一键按键召唤,到可选渲染器配置,3 分钟内完成全部上手。

herdr-file-viewer 终端文件查看器界面:左侧为目录树,右侧为语法高亮的 Cargo.toml 内容

先检查这 3 个前提条件

在开始之前,确认你的环境满足以下要求:

要求 说明
herdr 0.7.5+ 查看器以 herdr 插件形式运行
Linux 或 macOS Windows 原生目前为 preview(WSL 可直接使用)
Git 在 PATH 中 用于目录树状态标记与 diff 视图;没有 Git 也能打开,只是相关功能降级

安装时不需要 Rust 工具链:有预编译二进制时会直接下载(含 SHA-256 校验),只有在平台不支持或版本尚未发布时才会从源码编译。详见 docs/install.md。

第 1 步:一条命令安装 herdr 插件

打开终端,执行:

herdr plugin install smarzban/herdr-file-viewer

这一条命令同时完成了安装和更新,以后想升级最新版,重复执行即可。用 herdr plugin list 可以确认插件已注册,并能看到插件所在目录(后面装渲染器会用到)。

💡 如果某个版本需要可复现地固定住,可加 --ref v1.0.0 这类参数钉住旧版本;平时保持最新不需要它。

第 2 步:给文件查看器绑一个召唤按键

插件装好只注册了"动作",还需要在 herdr 配置里绑一个快捷键,才能实现一按即开。编辑 ~/.config/herdr/config.toml,加入:

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer"
description = "open file viewer in split"

[[keys.command]]
key = "prefix+shift+f"
type = "plugin_action"
command = "herdr-file-viewer.open-file-viewer-tab"
description = "open file viewer in tab"

然后执行 herdr server reload-config,之后在 herdr 里按下你的按键即可。召唤器是幂等的:没开→打开并聚焦;已开未聚焦→聚焦;已聚焦→关闭,一个按键就是开/关切换。

不想先绑键?也可以直接从 CLI 召唤一次:

herdr plugin action invoke open-file-viewer --plugin herdr-file-viewer

四个开箱即用的动作一览(完整说明见 docs/summoning.md):

动作 效果 推荐绑定
open-file-viewer 在当前面板旁分屏打开 prefix+f
open-file-viewer-tab 在独立 Tab 中打开 prefix+shift+f
open-file-viewer-at 弹窗输入目录,在指定位置分屏打开 prefix+d
open-file-viewer-at-tab 同上,但在新 Tab 打开 prefix+alt+d

⚠️ 记住一个高频坑:查看器聚焦后,搜索项目内容直接按裸键 s,而不是 prefix+s(那是 herdr 自带设置页的快捷键)。查看器内部按键都不需要 herdr 前缀。

第 3 步(推荐):安装渲染器,告别纯文本

查看器把渲染委托给三个可选的外部工具;不装也能用(自动降级为纯文本并给出提示,不会崩溃):

视图 渲染器 macOS 安装命令
渲染 Markdown glow brew install glow
渲染 diff delta brew install git-delta
代码语法高亮 bat brew install bat

最省事的办法是运行插件自带的一键脚本(自动识别 brew / apt / dnf / pacman,已装会跳过,可重复执行):

# 先进入 herdr plugin list 显示的插件目录
./scripts/install-renderers.sh

脚本源码在 scripts/install-renderers.sh。装好后,README 这类 Markdown 会以带颜色标题、行内代码块的形式呈现,完全融入你的终端主题:

herdr-file-viewer 渲染的 Markdown 文件:彩色标题与行内代码,左侧是带 Git 状态标记的目录树

渲染器也可以换:在插件配置中修改 markdown / diff / syntax 命令即可,完整参考见 docs/renderers.md。

30 秒键盘速览:装完立刻试试这些按键

按键 做什么
f 模糊查找任意文件
s 搜索项目内容,Enter 直接跳到 path:line
p 固定(Pin)当前文件到右侧,方便对比
v 循环切换视图:diff ⇄ 渲染 ⇄ 语法高亮
] / [ 跳到下一个 / 上一个有改动的文件
W 切换 git worktree
Z 当前文件全屏
e 在你的编辑器中打开(查看器挂起,编辑完自动回来)
? 帮助浮层:What's New、按键表、当前设置

用 Z 全屏后,整块终端都归文件所有,适合长代码阅读:

herdr-file-viewer 全屏模式:目录树加带行号的 Rust 源码占满整个终端

按 p 可以把某个文件"冻结"在右侧作为参考,继续浏览也不会丢——左边是目录树和当前文件,最右边是固定预览:

herdr-file-viewer 固定预览布局:左侧目录树、中间当前文件、右侧冻结的 Pinned 文件

完整按键与鼠标手势表见 docs/keys.md。

可选进阶:自定义 config.toml

想改编辑器命令、渲染器命令、树布局或按键映射?插件目录里附了一份全注释的示例 config.example.toml:

  1. 运行 herdr plugin config-dir herdr-file-viewer 打印配置目录;
  2. 把 config.example.toml 复制为 config.toml 放进去;
  3. 解开需要的行注释即可。

配置是只读输入,重启查看器生效;当前生效的设置随时可以在 ? 帮助浮层的 Settings 页查看。所有键位说明在 docs/configuration.md。

常见疑问速答

  • 如何更新? herdr 没有插件自动更新,重新执行一遍 herdr plugin install smarzban/herdr-file-viewer 就是更新。查看器内置的远程提醒最多 24 小时查一次,离线也不影响使用。
  • 它会改我的文件吗? 不会。查看器是只读的,e 键打开外部编辑器也只是"移交",改完退出即回到查看器。
  • 没有渲染器会怎样? 内容区会显示纯文本,并提示缺少哪个渲染器(如 "Markdown renderer (glow) not found"),功能不受影响。
  • agent 能不能直接定位到某一行? 可以。装上仓库附带的 skills/herdr-file-viewer/SKILL.md,说一声"打开 src/app.rs:42"就会直接落在那一行;标记范围后还能把备注复制回聊天。

到这里,herdr-file-viewer 的文件查看器、diff 浏览与 Markdown 渲染就全部就绪了。更多用法(标注、复制行引用、worktree 对比等)可继续阅读 docs/usage.md 使用指南。祝使用愉快 🚀

登录后查看全文
herdr-file-viewer