herdr-file-viewer

Herdr ファイルビューアー

ユーザーが Herdr ファイルビューアー（「Files」とも呼ばれます）でファイル、ソース行、範囲、または関数を開く、表示する、あるいは見せるよう求めた場合に、このスキルを使用します。変更箇所の候補を特定できたときに、ユーザーにその場所を見せる提案をする場合にも使用します。

場所を特定する

ビューアーを起動する前に、リクエストの対象をリポジトリ相対パスに解決します。

• ファイル：src/app.rs
• ソースの1行：src/app.rs:42
• ソースの範囲（終端行を含む）：src/app.rs:42-58

関数またはヘルパーの場合は、その定義を特定し、呼び出し箇所ではなく定義行を使用します。実質的に異なる候補が複数あり、文脈から特定できない場合は、推測するのではなく、簡潔な質問をします。バグが疑われる行については、実際に確認された失敗箇所と仮説を区別し、推測した場所を確定事項として示さないでください。

Herdr で開く（Linux、macOS、または WSL）

新しい Files ペインを起動します。

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 しても変更されません。ツール呼び出しはそのペインのシェルの外部で実行され、ビューアーのルートはそのペインが現在どこを指しているかによって決まるためです。対象のリポジトリでない可能性がある場合は、2つ目の --env を使用し、リポジトリまたはワークツリーへの絶対パスを明示してルートを指定します（その中の任意のディレクトリを指定すると、トップレベルに解決されます）。

# `$repo` is the target repository's absolute path, shell-escaped when assigned.
herdr plugin pane open --plugin herdr-file-viewer --entrypoint file-viewer \
  --placement split --direction right --focus \
  --env "HERDR_FILE_VIEWER_ROOT=$repo" \
  --env "HERDR_FILE_VIEWER_OPEN=src/app.rs:42"

相対パスまたは存在しない HERDR_FILE_VIEWER_ROOT は無視され、通常どおりフォーカスされているペインがビューアーのルートになります。表示されたツリー（ルート行と、ツリーの境界線にあるブランチ名）を確認し、対象のリポジトリが正しいことを確かめます。違うリポジトリが表示された場合は、開いたばかりのペインを閉じ、正しい HERDR_FILE_VIEWER_ROOT を指定して起動し直します。

対象はシェルのコードではなくデータとして扱います。HERDR_FILE_VIEWER_OPEN=<target>（および HERDR_FILE_VIEWER_ROOT=<dir>）をそれぞれ1つの引数として渡す、構造化された argv またはプロセス API を優先してください。シェルでは、生のパスをコマンドテキストに埋め込まないでください。代入時にシェル用にエスケープし、変数の展開は二重引用符の中でのみ行います。

TUI のキー入力をスクリプトで操作しないでください。自分が開いたばかりではない Files ペインを閉じたり、フォーカスしたり、対象を切り替えようとしたりしないでください。起動時に指定した対象が適用されるのは、新しいビューアーの起動時だけです。すでに開いているペインには、ユーザーの注釈や移動状態が残っている場合があります。

ネイティブ Windows のプレビュー

Windows ランチャーでは Files を開けますが、開く対象を指定できず、herdr plugin pane open ではネイティブ Windows 上でマニフェストのエントリーポイントを起動できません。対象を指定するリクエストには、上記のコマンドを使って WSL を利用します。バイナリがすでに PATH にある場合は、ビューアー専用にするターミナルで herdr-file-viewer.exe --open "<target>" を実行します。Windows の一般的な Files 操作で、指定された場所が開いたとは言わないでください。

Herdr の外部でバイナリが PATH にある場合は、直接実行します。

herdr-file-viewer --open src/app.rs:42

会話での動作

ユーザーが場所を直接見たいと頼んだ場合は、対象を解決してから開きます。診断や変更点を説明する際に場所の候補を特定できた場合は、「設定を変更する場所を表示しましょうか？」のような簡潔な質問をします。ユーザーが確認した後に開きます。

起動後は、開いた正確な対象を伝えます。ビューアーのルート内に実在するファイルとして対象を解決できない場合は、任意の場所やルート外のパスを開くのではなく、その旨を説明します。