Back to Details

herdr-file-viewer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Herdr File Viewer

Herdr File Viewer

Use this skill when the user asks to open, show, or reveal a file, source line, range, or function in the Herdr file viewer (also called "Files"). Use it when you have identified a likely change and offer to show the user where it is.
当用户要求在Herdr文件查看器（也称为“Files”）中打开、显示或查看某个文件、源代码行、范围或函数时，使用此技能。当你确定了一个可能的变更点，并想要向用户展示其位置时，也可以使用该技能。

Resolve the location

解析位置

Resolve the request to a repository-relative target before launching the viewer:
  • File: 
    src/app.rs
  • One source line: 
    src/app.rs:42
  • Inclusive source range: 
    src/app.rs:42-58
For a function or helper, locate its definition and use its definition line, not a call site. If there are materially different matches and context does not identify one, ask a short question instead of guessing. For a suspected bug line, distinguish an observed failure location from a hypothesis; do not present a guessed location as certain.
在启动查看器之前，将请求解析为相对于仓库的目标：
  • 文件：
    src/app.rs
  • 单行源代码：
    src/app.rs:42
  • 包含性源代码范围：
    src/app.rs:42-58
对于函数或辅助程序，定位其定义所在行，而非调用位置。如果存在多个差异明显的匹配项且上下文无法确定具体目标，应提出简短问题而非猜测。对于疑似错误的代码行，需区分观察到的故障位置与假设；不要将猜测的位置当作确定的结果展示。

Open it in Herdr (Linux, macOS, or WSL)

在Herdr中打开（Linux、macOS或WSL环境）

Launch a fresh Files pane:
bash
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer --placement split --direction right --focus --env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"
Replace the example target with the resolved file, line, or range. The viewer loads the file and scrolls to the requested location. A range receives a brief highlight.
Do not add 
--cwd
, and do not inject 
HERDR_PLUGIN_CONTEXT_JSON
. herdr resolves the relative pane command against 
--cwd
, so the launch fails everywhere except inside a built plugin checkout, where it silently runs THAT checkout's binary instead of the installed one. An injected context value is regenerated by herdr and discarded.
The viewed root comes from the focused herdr pane's working directory (resolved to that repository's worktree top level), so 
cd
-ing in your own process does not move it — your tool calls run outside that pane's shell, and the viewer roots wherever that pane happens to be. When it may not be in the target repository, give the launch a pane whose cwd IS that repository, then drop it; the root is captured at launch:
bash
undefined
启动一个新的Files面板：
bash
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer --placement split --direction right --focus --env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"
将示例目标替换为解析后的文件、行或范围。查看器会加载文件并滚动到请求的位置，范围内容会被短暂高亮显示。
不要添加
--cwd
参数，也不要注入
HERDR_PLUGIN_CONTEXT_JSON
。herdr会基于
--cwd
解析相对面板命令，因此除了在已构建的插件检出目录内，其他环境下启动都会失败；而在插件检出目录内时，会静默运行该检出目录的二进制文件，而非已安装的版本。注入的上下文值会被herdr重新生成并丢弃。
查看的根目录来自当前聚焦的herdr面板的工作目录（解析为该仓库工作树的顶层目录），因此在你自己的进程中执行
cd
命令不会改变它——你的工具调用在该面板的shell外部运行，查看器的根目录由该面板当前的位置决定。当不确定面板是否位于目标仓库中时，先创建一个工作目录为目标仓库的面板，然后再关闭它；根目录会在启动时被捕获：
bash
undefined

$repo
is the target repository or worktree (any directory inside it), shell-escaped when assigned.

$repo
是目标仓库或工作树（其中的任意目录），赋值时需进行shell转义。

helper=$(herdr pane split --current --direction right --cwd "$repo" --focus
| python3 -c 'import json,sys;print(json.load(sys.stdin)["result"]["pane"]["pane_id"])')
helper=$(herdr pane split --current --direction right --cwd "$repo" --focus
| python3 -c 'import json,sys;print(json.load(sys.stdin)["result"]["pane"]["pane_id"])')

Or with jq: ... | jq -r '.result.pane.pane_id'

或者使用jq：... | jq -r '.result.pane.pane_id'

[ -n "$helper" ] || exit 1 # the split failed: stop, or the launch below roots at the wrong pane
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer
--placement split --direction right --focus
--env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"
herdr pane close "$helper" # run this even if the launch failed, so no helper is left behind

Confirm you targeted the right repository from the rendered tree (root row, and the branch in the
tree border), not from the opened pane's reported `cwd` — that is the plugin's own directory, which
looks wrong but is expected. If the tree shows the wrong repository, close the pane you just opened
and relaunch with the helper recipe above.

Treat the target as data, never shell source. Prefer a structured argv or process API that passes
`HERDR_FILE_VIEWER_OPEN=<target>` as one argument. In a shell, do not interpolate a raw path into
command text: shell-escape it when assigning it, then expand the variable only inside double quotes.

Do not key-script the TUI. Do not close, focus, or try to retarget a Files pane you did not just
open: launch open targets are applied only when a new viewer starts, and a pane that was already
there may contain the user's annotations or navigation state.
[ -n "$helper" ] || exit 1 # 拆分失败：停止操作，否则下方的启动会使用错误的面板根目录
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer
--placement split --direction right --focus
--env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"
herdr pane close "$helper" # 即使启动失败也要执行此命令，避免遗留辅助面板

确认你定位的是正确的仓库，依据是渲染树的根目录行以及树边框中的分支，而非已打开面板报告的`cwd`——该路径是插件自身的目录，看似错误但属于正常情况。如果树显示的是错误的仓库，请关闭刚刚打开的面板，然后使用上述辅助面板的方法重新启动。

将目标视为数据，绝不要作为shell源代码处理。优先使用结构化的argv或进程API，将`HERDR_FILE_VIEWER_OPEN=<target>`作为单个参数传递。在shell中，不要将原始路径直接插入命令文本：赋值时需进行shell转义，然后仅在双引号内展开变量。

不要对TUI进行按键脚本操作。不要关闭、聚焦或尝试重新定位你未刚打开的Files面板：启动时的打开目标仅在新查看器启动时生效，已存在的面板可能包含用户的注释或导航状态。

Native Windows preview

原生Windows预览

The Windows launcher can open Files, but it does not accept an open target, and 
herdr plugin pane open
cannot start the manifest entrypoint on native Windows. For a targeted request, use WSL with the command above. If the binary is already on 
PATH
, run 
herdr-file-viewer.exe --open "<target>"
in a terminal you intend to devote to the viewer. Do not say a generic Windows Files action opened the requested location.
Outside Herdr, if the binary is on 
PATH
, run it directly:
bash
herdr-file-viewer --open src/app.rs:42
Windows启动器可以打开Files，但不接受打开目标，且
herdr plugin pane open
无法在原生Windows上启动清单入口点。对于定向请求，请使用WSL并执行上述命令。如果二进制文件已在
PATH
中，可在专用于查看器的终端中运行
herdr-file-viewer.exe --open "<target>"
。不要笼统地说Windows Files操作打开了请求的位置。
在Herdr外部，如果二进制文件在
PATH
中，可直接运行：
bash
herdr-file-viewer --open src/app.rs:42

Conversation behavior

对话行为

When the user directly asks to see a location, open it after resolving the target. When you have identified a likely location while explaining a diagnosis or change, offer a short question such as "Want me to show you where to change that setting?" Open it after the user confirms.
After launching, state the exact target you opened. If the target cannot be resolved to a real file under the viewer root, explain that rather than opening an arbitrary or outside-root path.
当用户直接要求查看某个位置时，解析目标后打开它。当你在解释诊断结果或变更时确定了一个可能的位置，可提出简短问题，例如“需要我为你展示该设置的修改位置吗？”，在用户确认后再打开。
启动后，说明你打开的具体目标。如果目标无法解析为查看器根目录下的真实文件，请进行解释，而非打开任意或根目录外的路径。