如何 3 分钟装好 herdr-file-viewer:从插件安装、按键召唤到渲染器配置的新手快速上手教程
如何 3 分钟装好 herdr-file-viewer:从插件安装、按键召唤到渲染器配置的新手快速上手教程
herdr-file-viewer 是一个为 herdr 打造的 git 感知、只读终端文件查看器(file viewer):左侧是带 Git 状态标记的目录树,右侧自动给出文件最合适的视图——有改动就显示 diff,Markdown 直接渲染,代码则带语法高亮。全文键盘驱动、鼠标可选,且永不修改你的文件。本文带你从插件安装、一键按键召唤,到可选渲染器配置,3 分钟内完成全部上手。
先检查这 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 会以带颜色标题、行内代码块的形式呈现,完全融入你的终端主题:
渲染器也可以换:在插件配置中修改 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 全屏后,整块终端都归文件所有,适合长代码阅读:
按 p 可以把某个文件"冻结"在右侧作为参考,继续浏览也不会丢——左边是目录树和当前文件,最右边是固定预览:
完整按键与鼠标手势表见 docs/keys.md。
可选进阶:自定义 config.toml
想改编辑器命令、渲染器命令、树布局或按键映射?插件目录里附了一份全注释的示例 config.example.toml:
- 运行
herdr plugin config-dir herdr-file-viewer打印配置目录; - 把
config.example.toml复制为config.toml放进去; - 解开需要的行注释即可。
配置是只读输入,重启查看器生效;当前生效的设置随时可以在 ? 帮助浮层的 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 使用指南。祝使用愉快 🚀



