diff options
| author | kangal-bot <285672167+kangal-bot@users.noreply.github.com> | 2026-09-06 10:42:13 +0000 |
|---|---|---|
| committer | kangal-bot <285672167+kangal-bot@users.noreply.github.com> | 2026-09-06 10:42:13 +0000 |
| commit | e366a05f03b6e37549c7a1744c3551553017c541 (patch) | |
| tree | 76656b0a6760eb82b6e00d70cf27473696404946 /docs/preview | |
| parent | 9e9bc8a144667a6b7debfd4f0c7a31ff0e11493a (diff) | |
docs: publish preview documentation
Diffstat (limited to 'docs/preview')
35 files changed, 282 insertions, 126 deletions
diff --git a/docs/preview/website/src/content/docs/agent-automation.mdx b/docs/preview/website/src/content/docs/agent-automation.mdx index b1b128f5..237162fb 100644 --- a/docs/preview/website/src/content/docs/agent-automation.mdx +++ b/docs/preview/website/src/content/docs/agent-automation.mdx @@ -73,7 +73,7 @@ herdr agent rename w1:p2 reviewer Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane. -`agent prompt --wait` submits immediately unless the agent is already `blocked`, in which case it returns `agent_blocked` without starting the wait. If an accepted prompt starts from another non-working state, Herdr must observe a lifecycle change within five seconds. Otherwise, it returns `agent_prompt_stalled` instead of waiting indefinitely; a caller `--timeout` of five seconds or less returns the normal `timeout` error. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`. +`agent prompt --wait` submits immediately unless the agent is already `blocked`, in which case it returns `agent_blocked` without starting the wait. If an accepted prompt starts from another non-working state, Herdr must observe `working` or `blocked` within five seconds. Otherwise, it returns `agent_prompt_stalled`; if the caller timeout expires first, it returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`. `idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after background work finishes, until that tab is focused or `pane focus` / `agent focus` targets it. Reading through the CLI does not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters. diff --git a/docs/preview/website/src/content/docs/cli-reference.mdx b/docs/preview/website/src/content/docs/cli-reference.mdx index 189be5b0..d82a550a 100644 --- a/docs/preview/website/src/content/docs/cli-reference.mdx +++ b/docs/preview/website/src/content/docs/cli-reference.mdx @@ -15,7 +15,6 @@ herdr --session work # launch or attach to a named session herdr --remote workbox # attach through SSH, using local keybindings herdr --remote workbox --remote-keybindings server herdr --remote workbox --handoff -herdr --no-session # single-process escape hatch herdr --default-config # print default config herdr update # download and install from the configured channel herdr update --handoff # opt into live handoff for supported running servers @@ -46,6 +45,23 @@ herdr api schema --output herdr-api.schema.json with the installed binary. Use `--json` for the full JSON Schema document, or `--output PATH` to write that document to a file. +## Saved SSH machines + +```bash +herdr machine list [--json] +herdr machine add workbox --label "Build machine" [--remote-session agents] +herdr machine rename <profile-id> --label "New name" +herdr machine disable <profile-id> +herdr machine enable <profile-id> +herdr machine remove <profile-id> +``` + +`machine add` checks the remote installation's capabilities, installs or updates with approval only when needed, and starts the requested session's background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. + +Changes apply automatically to open local Herdr clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdr does not store passwords, private keys, or other SSH credentials. + +Automatic connections and reconnects are non-interactive. If a host key, password, key passphrase, MFA step, install, update, or restart needs approval, the machine shows Attention instead of opening a hidden prompt. Run the standalone command printed by Herdr, such as `herdr --remote workbox --session agents --handoff`, to complete that setup in the foreground, then restart the client. + ## Shell completions ```bash @@ -311,7 +327,7 @@ Agent targets are either a unique live agent name or the pane ID that currently A successful start returns only after the expected agent owns the same terminal and is ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. The default startup timeout is 30000 milliseconds; explicit values must be greater than 3000 and no more than 300000. -`agent prompt` honors live bracketed-paste mode and sends text followed by encoded Enter after a short delay, including while the agent is working. If the agent is already `blocked`, it returns `agent_blocked` without sending input. With `--wait`, an accepted prompt sent from another non-working state must produce an observed lifecycle change within five seconds or Herdr returns `agent_prompt_stalled`; a caller timeout of five seconds or less keeps the normal `timeout` error. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed. +`agent prompt` honors live bracketed-paste mode and sends text followed by encoded Enter after a short delay, including while the agent is working. If the agent is already `blocked`, it returns `agent_blocked` without sending input. With `--wait`, an accepted prompt sent from another non-working state must produce an observed `working` or `blocked` state within five seconds or Herdr returns `agent_prompt_stalled`; if the caller timeout expires first, Herdr returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After activity is observed, it waits for the first requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. `--until` narrows the matching states and is rejected unless `--wait` is also present. Standalone `agent wait` returns immediately when the current status matches. Both default to `idle`, `done`, or `blocked`; use `--until unknown` explicitly when needed. `idle` means ready for input after its tab has been seen in the focused Herdr UI; `done` is the same underlying idle state after unseen background work completes. Focusing that tab or targeting it with `pane focus` / `agent focus` marks it seen; reading it through the CLI does not. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently, not that its work succeeded. @@ -357,7 +373,7 @@ Use `pane wait-output` for normal commands and servers. Use `agent wait` for cod `pane wait-output` checks the selected snapshot immediately, including output that already exists, then polls until it matches. The default source name is `recent`; matching treats it as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit. `--match` finds a literal substring on one line, and `--regex` uses Rust regular-expression syntax and also matches one line at a time. -`pane wait-output`, `agent wait`, and `agent prompt --wait` wait indefinitely when `--timeout` is omitted. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2. +`pane wait-output` and `agent wait` wait indefinitely when `--timeout` is omitted. For `agent prompt --wait`, the settled-state wait is indefinite after activity is observed or when the prompt starts in `working`; a non-working prompt still returns `agent_prompt_stalled` after five seconds without observed activity. A timeout or server error is emitted as JSON on stderr with exit status 1. CLI usage errors exit with status 2. ## Integrations diff --git a/docs/preview/website/src/content/docs/concepts.mdx b/docs/preview/website/src/content/docs/concepts.mdx index 733da1bb..7641b17f 100644 --- a/docs/preview/website/src/content/docs/concepts.mdx +++ b/docs/preview/website/src/content/docs/concepts.mdx @@ -68,6 +68,8 @@ By default, Herdr runs as a background server plus one or more attached clients. The server owns panes and process state. The client is the terminal UI attached to that server. +With one attached client, all tabs follow its size as before. With multiple clients, each can view its own workspace and tab. Different viewed tabs follow their respective clients; when clients view the same tab, the last one to focus, select, or interact with it controls that tab's pane sizes. + Detach the client with `ctrl+b q`. The server and agents continue running. If you want to end the session and stop its panes, stop the server: diff --git a/docs/preview/website/src/content/docs/configuration.mdx b/docs/preview/website/src/content/docs/configuration.mdx index 222a5d68..63ce3186 100644 --- a/docs/preview/website/src/content/docs/configuration.mdx +++ b/docs/preview/website/src/content/docs/configuration.mdx @@ -60,7 +60,7 @@ headless_cols = 160 headless_rows = 50 ``` -An attached client remains authoritative for the shared runtime size. After it detaches, existing pane PTYs retain their last attached size while new headless layout uses the configured fallback. +With one attached client, all tabs follow its size. With multiple clients, each viewed tab follows the client that most recently focused, selected, or interacted with it. When all but one client detach, all tabs immediately return to the remaining client's size. When no clients remain, existing pane PTYs retain their last size and new headless layout uses the configured fallback. ## Terminal defaults @@ -352,7 +352,7 @@ The expanded desktop sidebar renders each inner array in `rows` as one line. The [ui.sidebar.agents] row_gap = 0 rows = [ - ["state_icon", "workspace", "tab"], + ["state_icon", "machine", "workspace", "tab"], ["agent"], ] @@ -368,6 +368,7 @@ Agent rows accept these built-in tokens: - `state_icon` — colored icon for the agent's semantic state. - `state_text` — `idle`, `working`, `blocked`, `done`, or `unknown`, including a reported display label when present. +- `machine` — machine label when the client has multiple machines; omitted for a single local machine. - `workspace` — workspace name. - `tab` — tab name when available. - `pane` — pane name when available. @@ -385,7 +386,7 @@ Space rows accept these built-in tokens: - `git_status` — Git ahead and behind counts when nonzero. - `$name` — custom workspace metadata named `name`. -Tokens render in their configured order. Herdr normally separates adjacent values with ` · ` and uses a single space after `state_icon`. Missing values and their separators disappear; a row disappears when none of its tokens have a value. Each layout may contain at most 16 rows, with at most 16 tokens in each row. +Tokens render in their configured order. Herdr normally separates adjacent values with ` · ` and uses a single space after `state_icon`. Missing values and their separators disappear; a row disappears when none of its tokens have a value. Existing custom rows remain unchanged, so add `machine` explicitly if you want machine identity in a custom multi-machine layout. Each layout may contain at most 16 rows, with at most 16 tokens in each row. A token entry can also be an inline style table: @@ -488,14 +489,16 @@ Search the [Config reference](/docs/config-reference/) for scrollback limits, ne ## Kitty graphics -Kitty graphics rendering for attached local clients is experimental and disabled by default: +Herdr renders pane images by default in compatible outer terminals. To disable graphics rendering and the pane graphics API: ```toml -[experimental] -kitty_graphics = true +[terminal] +kitty_graphics = false ``` -Enable it only when testing terminal image behavior. +The legacy `experimental.kitty_graphics` setting remains accepted for existing configurations. `terminal.kitty_graphics` takes precedence when both are set. + +Changing this setting requires restarting the affected Herdr server or reattaching the client. In remote sessions, the server's setting controls pane graphics parsing and API availability, while the local client's setting controls output to the outer terminal. ## Agent session restore diff --git a/docs/preview/website/src/content/docs/how-to-work.mdx b/docs/preview/website/src/content/docs/how-to-work.mdx index 8d3ad081..6e74e59d 100644 --- a/docs/preview/website/src/content/docs/how-to-work.mdx +++ b/docs/preview/website/src/content/docs/how-to-work.mdx @@ -100,4 +100,4 @@ herdr --remote workbox Use `herdr` for local work. Use `ssh you@server` then `herdr` when you want Herdr to behave like tmux on that remote shell or when you are using a phone SSH client. Use `herdr --remote <host>` when you want a local thin client for a remote session, including local clipboard image paste bridging. -For remote bootstrap details, named remote sessions, custom binaries, direct terminal attach, and `--no-session`, see [Persistence and remote access](/docs/persistence-remote/). +For remote bootstrap details, named remote sessions, custom binaries, and direct terminal attach, see [Persistence and remote access](/docs/persistence-remote/). diff --git a/docs/preview/website/src/content/docs/install.mdx b/docs/preview/website/src/content/docs/install.mdx index a14a1d5b..c0c422a5 100644 --- a/docs/preview/website/src/content/docs/install.mdx +++ b/docs/preview/website/src/content/docs/install.mdx @@ -25,7 +25,7 @@ If endpoint security blocks that fileless PowerShell command, open Command Promp curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd ``` -The installer downloads the release binary for your platform and places it on your PATH. New direct installs use the stable update channel. Existing Windows preview installs stay on preview until you switch them with `herdr channel set stable`. The Windows installer uses versioned install folders and updates a `current` junction, so updates do not need to overwrite a running `herdr.exe`. +The installer downloads the release binary for your platform and places it on your PATH. New direct installs use the stable update channel. Existing Windows preview installs stay on preview until you switch them with `herdr channel set stable`. On Windows, PATH points to the active versioned release directory; the installer also updates the `current` and stable `bin` compatibility aliases, so updates do not need to overwrite a running `herdr.exe`. ## Install with Homebrew @@ -139,7 +139,7 @@ Preview builds are regularly published GitHub prereleases from the current devel Stable is the recommended channel for normal Windows use. Preview receives fixes sooner but can regress, so opt in only when you want that tradeoff. Existing Windows preview installs remain on preview until you switch them explicitly. If an older preview build rejects `herdr channel set stable`, run `herdr update` once on preview, then retry the channel switch. -By default, `herdr update` installs the new binary and leaves compatible running sessions alone. If an update changes Herdr's client/server protocol, Herdr asks whether to stop the old server after installing. Stop the old server to use the new version. Stopping the server exits its pane processes. For the default session, run `herdr server stop`, then run `herdr` again. For a named session, run `herdr session stop <name>`, then run `herdr session attach <name>` again. +By default, `herdr update` installs the new binary and leaves endpoint-generation-1 servers and their pane processes running. Start Herdr again to reconnect with the updated client. Client-only changes work immediately. A new server-side action stays unavailable until that server is updated and restarted; the client shows a notice instead of disconnecting. Servers from before endpoint generation 1 need one final stop during update. To opt into experimental live server handoff for supported running sessions, run: @@ -147,7 +147,7 @@ To opt into experimental live server handoff for supported running sessions, run herdr update --handoff ``` -Live handoff does not apply to Homebrew, mise, or Nix package-manager updates. For those installs, update with the package manager, then restart that Herdr session when you are ready to use the new server. If a running session still uses the old server, stop it with `herdr server stop` or `herdr session stop <name>`, then run Herdr again. +Live handoff does not apply to Homebrew, mise, or Nix package-manager updates. For those installs, update with the package manager, then run Herdr again to reconnect with the updated client. The compatible old server keeps running. Restart it later with `herdr server stop` or `herdr session stop <name>` only when you want server-side changes from the new release. ## Requirements diff --git a/docs/preview/website/src/content/docs/integrations.mdx b/docs/preview/website/src/content/docs/integrations.mdx index 9fea14d3..1f64f2b9 100644 --- a/docs/preview/website/src/content/docs/integrations.mdx +++ b/docs/preview/website/src/content/docs/integrations.mdx @@ -175,9 +175,7 @@ herdr integration install devin The hook reports native session identity from Devin session, prompt, tool-use, permission, and stop events. Devin state still comes from Herdr's screen manifest and OSC detection because Devin hooks do not emit a reliable state transition after every permission cancellation or user interrupt. -On Linux and macOS, Herdr uses `~/.config/devin` by default, or `$XDG_CONFIG_HOME/devin` when `XDG_CONFIG_HOME` is set. The Devin config directory must already exist. Install writes `herdr-agent-state.sh` and updates `config.json` with Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdr entries from `config.json` and deletes the hook script. - -Devin integration installation is not currently supported on Windows. Devin stores its Windows config under `%APPDATA%\devin`, which Herdr does not yet resolve. Native process and screen detection still work without the hook. +Herdr uses `$XDG_CONFIG_HOME/devin` when `XDG_CONFIG_HOME` is set. Otherwise, it uses `~/.config/devin` on Linux and macOS or `%APPDATA%\devin` on Windows. The Devin config directory must already exist. Install writes `herdr-agent-state.sh` on Unix or `herdr-agent-state.ps1` on Windows and updates `config.json` with Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdr entries from `config.json` and deletes the hook script. Herdr resumes stored Devin sessions with `devin --resume <id>`. Native screen manifest detection remains the state authority whether or not the hook is installed. diff --git a/docs/preview/website/src/content/docs/ja/agent-automation.mdx b/docs/preview/website/src/content/docs/ja/agent-automation.mdx index ee52eed6..7e596d07 100644 --- a/docs/preview/website/src/content/docs/ja/agent-automation.mdx +++ b/docs/preview/website/src/content/docs/ja/agent-automation.mdx @@ -73,7 +73,7 @@ herdr agent rename w1:p2 reviewer ペイン入力は、現在のプロセスに関係なくターミナルを指定します。エージェント入力はライブエージェントを解決し、そのエージェントがペインを制御しなくなっていれば操作を拒否します。 -`agent prompt --wait` は、エージェントがすでに `blocked` でない限り、プロンプトをすぐ送信します。すでに `blocked` の場合は待機を開始せずに `agent_blocked` を返します。受け付けたプロンプトが別の non-working 状態から始まる場合、Herdr はまず 5 秒以内にライフサイクル変化が観測されることを要求します。状態シーケンスが進まなければ、無期限に待たず `agent_prompt_stalled` を返します。呼び出し側の `--timeout` が 5 秒以下なら、通常の `timeout` エラーを返します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。エージェントがすでに working の場合、進行中ターンの完了が待機を満たすことがあります。単独の `agent wait` は現在のエージェントを監視し、すでに状態が一致していれば即座に返ります。どちらもデフォルトでは `idle`、`done`、`blocked` を待ちます。複数の正確な状態を許可するには、`--until idle --until done` のように `--until` を繰り返します。`unknown` が必要な場合は `--until unknown` を明示してください。`agent prompt` では `--until` に `--wait` が必要です。 +`agent prompt --wait` は、エージェントがすでに `blocked` でない限り、プロンプトをすぐ送信します。すでに `blocked` の場合は待機を開始せずに `agent_blocked` を返します。受け付けたプロンプトが別の non-working 状態から始まる場合、Herdr は 5 秒以内に `working` または `blocked` を観測する必要があります。観測できなければ `agent_prompt_stalled` を返し、呼び出し側のタイムアウトが先に切れた場合は通常の `timeout` エラーを返します。これにより、無関係な `idle`、`done`、またはセッションの変化によって待機が誤って完了することを防ぎます。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。エージェントがすでに working の場合、進行中ターンの完了が待機を満たすことがあります。単独の `agent wait` は現在のエージェントを監視し、すでに状態が一致していれば即座に返ります。どちらもデフォルトでは `idle`、`done`、`blocked` を待ちます。複数の正確な状態を許可するには、`--until idle --until done` のように `--until` を繰り返します。`unknown` が必要な場合は `--until unknown` を明示してください。`agent prompt` では `--until` に `--wait` が必要です。 `idle` は、エージェントが入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みであることを示します。`done` は同じ基礎的な idle 状態ですが、バックグラウンド作業が完了してから、そのタブをフォーカスするか `pane focus` / `agent focus` で対象にするまで使われます。CLI で読み取るだけでは表示済みになりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。 diff --git a/docs/preview/website/src/content/docs/ja/cli-reference.mdx b/docs/preview/website/src/content/docs/ja/cli-reference.mdx index 0b3e06f3..7448297a 100644 --- a/docs/preview/website/src/content/docs/ja/cli-reference.mdx +++ b/docs/preview/website/src/content/docs/ja/cli-reference.mdx @@ -15,7 +15,6 @@ herdr --session work # 名前付きセッションを起動またはア herdr --remote workbox # SSH 越しにアタッチ (ローカルのキーバインドを使用) herdr --remote workbox --remote-keybindings server herdr --remote workbox --handoff -herdr --no-session # シングルプロセスの逃げ道 herdr --default-config # デフォルト設定を表示 herdr update # 設定済みチャンネルからダウンロードしてインストール herdr update --handoff # 対応する実行中サーバーでライブハンドオフにオプトイン @@ -44,6 +43,23 @@ herdr api schema --output herdr-api.schema.json `herdr api schema` は、インストール済みバイナリに同梱されたソケットプロトコルスキーマの短い概要を表示します。完全な JSON Schema ドキュメントが欲しいときは `--json` を使い、ファイルに書き出すには `--output PATH` を使ってください。 +## 保存済み SSH マシン + +```bash +herdr machine list [--json] +herdr machine add workbox --label "Build machine" [--remote-session agents] +herdr machine rename <profile-id> --label "New name" +herdr machine disable <profile-id> +herdr machine enable <profile-id> +herdr machine remove <profile-id> +``` + +`machine add` はリモート側の Herdr が必要な機能を備えているか確認し、必要な場合だけ承認を得てインストールまたは更新します。指定したセッションのバックグラウンドサーバーを起動してからプロファイルを保存します。互換性があればリリースバージョンは一致しなくてもかまいません。インストールや再起動の承認が必要な場合は、対話型ターミナルで実行してください。セットアップが失敗またはキャンセルされた場合、プロファイルは保存されません。 + +変更は、開いているローカルの Herdr クライアントに通常 1 秒以内に自動反映されます。追加または有効化したマシンにはバックグラウンドで接続し、名前の変更では再接続しません。削除または無効化すると、そのマシンだけが切断され、リモートセッションは動き続けます。表示中のマシンを削除すると Local に戻ります。Local に接続できない場合は、再接続するまで利用不可と表示します。各プロファイルは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態をクライアントの状態ファイルに保存します。パスワード、秘密鍵、その他の SSH 認証情報は保存しません。 + +自動接続と再接続は非対話型です。ホスト鍵、パスワード、鍵のパスフレーズ、MFA、インストール、更新、再起動に承認が必要な場合、隠れたプロンプトを開くのではなく Attention と表示します。`herdr --remote workbox --session agents --handoff` など、Herdr が表示する単独接続用のコマンドを実行してフォアグラウンドでセットアップを完了し、クライアントを再起動してください。 + ## シェル補完 ```bash @@ -291,7 +307,7 @@ herdr agent explain --file PATH --agent LABEL [--json|--verbose] 成功した start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。起動中の検出状態が `blocked` の場合、コマンドは直ちに `agent_not_ready` を返します。名前は `agent read` と `agent send-keys` で引き続き使用でき、検出状態が `idle` になるとプロンプトを送信できるようになります。デフォルトの起動タイムアウトは 30000 ミリ秒で、明示する値は 3000 より大きく 300000 以下でなければなりません。 -`agent prompt` は現在の bracketed paste モードを尊重し、working 中でもテキストを送信してから短い遅延の後にエンコード済み Enter を送信します。エージェントがすでに `blocked` の場合は、入力を送信せずに `agent_blocked` を返します。`--wait` を使う場合、別の non-working 状態から受け付けたプロンプトは 5 秒以内に観測可能なライフサイクル変化を起こす必要があり、変化がなければ Herdr は `agent_prompt_stalled` を返します。呼び出し側のタイムアウトが 5 秒以下なら、通常の `timeout` エラーを維持します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。`--until` は一致状態を絞り込み、`--wait` なしでは拒否されます。単独の `agent wait` は現在の状態が一致すれば即座に返ります。どちらもデフォルトは `idle`、`done`、`blocked` です。 +`agent prompt` は現在の bracketed paste モードを尊重し、working 中でもテキストを送信してから短い遅延の後にエンコード済み Enter を送信します。エージェントがすでに `blocked` の場合は、入力を送信せずに `agent_blocked` を返します。`--wait` を使う場合、別の non-working 状態から受け付けたプロンプトでは、5 秒以内に `working` または `blocked` が観測される必要があります。観測できなければ Herdr は `agent_prompt_stalled` を返し、呼び出し側のタイムアウトが先に切れた場合は通常の `timeout` エラーを返します。これにより、無関係な `idle`、`done`、またはセッションの変化によって待機が誤って完了することを防ぎます。活動を観測した後、要求された最初の安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。`--until` は一致状態を絞り込み、`--wait` なしでは拒否されます。単独の `agent wait` は現在の状態が一致すれば即座に返ります。どちらもデフォルトは `idle`、`done`、`blocked` です。 `idle` は入力待ちで、そのタブがフォーカス中の Herdr UI ですでに表示済みの状態です。`done` は同じ基礎的な idle 状態ですが、表示していないバックグラウンド作業が完了したときに使われます。そのタブをフォーカスするか `pane focus` / `agent focus` で対象にすると表示済みになりますが、CLI で読み取るだけでは変わりません。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するものの確実に分類できない状態で、作業の成功を意味しません。 @@ -324,7 +340,7 @@ herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source `pane wait-output` は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更できます。`--match` は 1 行内のリテラル部分文字列を検索し、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。 -`pane wait-output`、`agent wait`、`agent prompt --wait` は、`--timeout` を省略すると無期限に待ちます。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。 +`pane wait-output` と `agent wait` は、`--timeout` を省略すると無期限に待ちます。`agent prompt --wait` では、活動を観測した後、またはプロンプト開始時に `working` だった場合の安定状態待機は無期限です。non-working 状態から開始して活動を観測できない場合は、5 秒後に `agent_prompt_stalled` を返します。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。 ## インテグレーション diff --git a/docs/preview/website/src/content/docs/ja/concepts.mdx b/docs/preview/website/src/content/docs/ja/concepts.mdx index 640ba8a4..69bcb1e6 100644 --- a/docs/preview/website/src/content/docs/ja/concepts.mdx +++ b/docs/preview/website/src/content/docs/ja/concepts.mdx @@ -68,6 +68,8 @@ herdr session attach side-project サーバーはペインとプロセス状態を所有します。クライアントはそのサーバーにアタッチしたターミナル UI です。 +クライアントが 1 つだけ接続されている場合、従来どおりすべてのタブがそのサイズに従います。複数のクライアントが接続されている場合、それぞれ別のワークスペースやタブを表示できます。異なるタブはそれぞれを表示するクライアントのサイズに従い、同じタブを表示している場合は、最後にそのタブへフォーカス、選択、または操作したクライアントがペインのサイズを制御します。 + `ctrl+b q` でクライアントをデタッチします。サーバーとエージェントは動き続けます。 セッションを終了してそのペインを停止したい場合は、サーバーを停止します: diff --git a/docs/preview/website/src/content/docs/ja/configuration.mdx b/docs/preview/website/src/content/docs/ja/configuration.mdx index b2af36c8..8377d56c 100644 --- a/docs/preview/website/src/content/docs/ja/configuration.mdx +++ b/docs/preview/website/src/content/docs/ja/configuration.mdx @@ -60,7 +60,7 @@ headless_cols = 160 headless_rows = 50 ``` -クライアントが接続されている間は、そのクライアントが共有ランタイムのサイズを決定します。切断後、既存のペイン PTY は最後に接続されていたときのサイズを保ち、新しいヘッドレスレイアウトには設定したフォールバックが使われます。 +クライアントが 1 つだけ接続されている場合、すべてのタブがそのサイズに従います。複数のクライアントが接続されている場合、表示中の各タブは、最後にそのタブへフォーカス、選択、または操作したクライアントのサイズに従います。1 つを除くすべてのクライアントが切断すると、すべてのタブは残ったクライアントのサイズへすぐに戻ります。クライアントが 1 つも残っていない場合、既存のペイン PTY は最後のサイズを保ち、新しいヘッドレスレイアウトには設定したフォールバックが使われます。 ## ターミナルのデフォルト @@ -348,7 +348,7 @@ status_indicators = "symbols" [ui.sidebar.agents] row_gap = 0 rows = [ - ["state_icon", "workspace", "tab"], + ["state_icon", "machine", "workspace", "tab"], ["agent"], ] @@ -364,6 +364,7 @@ Agent の行では、次の組み込みトークンを使えます: - `state_icon` — エージェントの意味的な状態を示す色付きアイコン。 - `state_text` — `idle`、`working`、`blocked`、`done`、`unknown`。報告された表示ラベルがある場合はそれも含みます。 +- `machine` — クライアントに複数のマシンがある場合のマシンラベル。ローカルマシン 1 台だけの場合は省略されます。 - `workspace` — ワークスペース名。 - `tab` — 利用可能な場合はタブ名。 - `pane` — 利用可能な場合はペイン名。 @@ -381,7 +382,7 @@ Space の行では、次の組み込みトークンを使えます: - `git_status` — 0 でない場合は Git の ahead と behind の件数。 - `$name` — `name` という名前のカスタムワークスペースメタデータ。 -トークンは設定された順序で描画されます。Herdr は通常、隣接する値を ` · ` で区切り、`state_icon` の後には空白を 1 つ入れます。値がない場合、その値と区切りは表示されません。すべてのトークンに値がない行は表示されません。各レイアウトは最大 16 行、各行は最大 16 トークンです。 +トークンは設定された順序で描画されます。Herdr は通常、隣接する値を ` · ` で区切り、`state_icon` の後には空白を 1 つ入れます。値がない場合、その値と区切りは表示されません。すべてのトークンに値がない行は表示されません。既存のカスタム行は変更されません。カスタムの複数マシンレイアウトでマシンを識別したい場合は、`machine` を明示的に追加してください。各レイアウトは最大 16 行、各行は最大 16 トークンです。 トークンエントリにはインラインのスタイルテーブルも使えます: @@ -484,14 +485,16 @@ claude = "on" ## Kitty graphics -アタッチされたローカルクライアントでの Kitty graphics の描画は実験的機能で、デフォルトでは無効です: +Herdr は、対応する外側のターミナルでペイン画像をデフォルトで描画します。グラフィックス描画とペイングラフィックス API を無効にするには、次のように設定します: ```toml -[experimental] -kitty_graphics = true +[terminal] +kitty_graphics = false ``` -ターミナルの画像表示をテストする場合にのみ有効にしてください。 +既存の設定との互換性のため、従来の `experimental.kitty_graphics` 設定も引き続き使用できます。両方が設定されている場合は、`terminal.kitty_graphics` が優先されます。 + +この設定を変更した場合は、対象の Herdr サーバーを再起動するか、クライアントを再アタッチする必要があります。リモートセッションでは、サーバー側の設定がペイングラフィックスの解析と API の可用性を制御し、ローカルクライアント側の設定が外側のターミナルへの出力を制御します。 ## Agent セッション復元 diff --git a/docs/preview/website/src/content/docs/ja/how-to-work.mdx b/docs/preview/website/src/content/docs/ja/how-to-work.mdx index 0365df0b..d6d6bd95 100644 --- a/docs/preview/website/src/content/docs/ja/how-to-work.mdx +++ b/docs/preview/website/src/content/docs/ja/how-to-work.mdx @@ -100,4 +100,4 @@ herdr --remote workbox ローカル作業には `herdr` を使います。リモートシェル上で Herdr を tmux のように使いたいときや、スマートフォンの SSH クライアントを使っているときは `ssh you@server` してから `herdr` を使います。リモートセッション用のローカルシンクライアントが欲しいとき (ローカルクリップボードの画像貼り付けブリッジを含む) は `herdr --remote <host>` を使います。 -リモートブートストラップの詳細、名前付きリモートセッション、カスタムバイナリ、ダイレクトターミナルアタッチ、`--no-session` については[永続化とリモートアクセス](/ja/docs/persistence-remote/)を参照してください。 +リモートブートストラップの詳細、名前付きリモートセッション、カスタムバイナリ、ダイレクトターミナルアタッチについては[永続化とリモートアクセス](/ja/docs/persistence-remote/)を参照してください。 diff --git a/docs/preview/website/src/content/docs/ja/install.mdx b/docs/preview/website/src/content/docs/ja/install.mdx index 72d591c8..8217d311 100644 --- a/docs/preview/website/src/content/docs/ja/install.mdx +++ b/docs/preview/website/src/content/docs/ja/install.mdx @@ -25,7 +25,7 @@ powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd ``` -インストーラーはプラットフォームに合ったリリースバイナリをダウンロードして PATH 上に配置します。新しい直接インストールは安定版アップデートチャンネルを使います。既存の Windows プレビューインストールは、`herdr channel set stable` で切り替えるまでプレビューに残ります。Windows インストーラーはバージョン付きインストールフォルダーを使い、`current` ジャンクションを更新します。そのため、アップデート時に実行中の `herdr.exe` を上書きする必要がありません。 +インストーラーはプラットフォームに合ったリリースバイナリをダウンロードして PATH 上に配置します。新しい直接インストールは安定版アップデートチャンネルを使います。既存の Windows プレビューインストールは、`herdr channel set stable` で切り替えるまでプレビューに残ります。Windows では PATH が有効なバージョン付きリリースディレクトリを指し、インストーラーは互換性のため `current` と安定した `bin` エイリアスも更新します。そのため、アップデート時に実行中の `herdr.exe` を上書きする必要がありません。 ## Homebrew でインストール @@ -139,7 +139,7 @@ herdr channel set stable Windows の通常利用には安定版を推奨します。プレビューでは修正をより早く受け取れますが、リグレッションの可能性があるため、そのトレードオフを望む場合に限りオプトインしてください。既存の Windows プレビューインストールは、明示的に切り替えるまでプレビューに残ります。古いプレビュービルドで `herdr channel set stable` が拒否される場合は、プレビューのまま一度 `herdr update` を実行してから、チャンネル切り替えを再試行してください。 -デフォルトでは、`herdr update` は新しいバイナリをインストールし、互換性のある実行中セッションには手を付けません。アップデートが Herdr のクライアント/サーバープロトコルを変更する場合、Herdr はインストール後に古いサーバーを停止するか尋ねます。新しいバージョンを使うには古いサーバーを停止してください。停止するとペインのプロセスは終了します。デフォルトセッションでは `herdr server stop` を実行してから再度 `herdr` を実行します。名前付きセッションでは `herdr session stop <name>` を実行してから再度 `herdr session attach <name>` を実行します。 +デフォルトでは、`herdr update` は新しいバイナリをインストールし、エンドポイント世代 1 のサーバーとペインプロセスを動かしたままにします。再度 Herdr を起動すると、更新済みクライアントで再接続します。クライアントだけの変更はすぐに使えます。新しいサーバー側アクションは、そのサーバーを更新して再起動するまで利用できず、クライアントは切断せずに通知を表示します。エンドポイント世代 1 より前のサーバーだけは、更新時に最後の 1 回の停止が必要です。 対応する実行中セッションで実験的なライブサーバーハンドオフにオプトインするには: @@ -147,7 +147,7 @@ Windows の通常利用には安定版を推奨します。プレビューでは herdr update --handoff ``` -ライブハンドオフは Homebrew、mise、Nix のパッケージマネージャー経由のアップデートには適用されません。それらのインストールではパッケージマネージャーでアップデートし、新しいサーバーを使う準備ができたらその Herdr セッションを再起動してください。実行中のセッションがまだ古いサーバーを使っている場合は、`herdr server stop` または `herdr session stop <name>` で停止してから、再度 Herdr を実行します。 +ライブハンドオフは Homebrew、mise、Nix のパッケージマネージャー経由のアップデートには適用されません。それらのインストールではパッケージマネージャーで更新し、再度 Herdr を実行して更新済みクライアントで再接続します。互換性のある古いサーバーは動き続けます。新しいリリースのサーバー側変更が必要になったときだけ、`herdr server stop` または `herdr session stop <name>` で後から再起動してください。 ## 動作要件 diff --git a/docs/preview/website/src/content/docs/ja/integrations.mdx b/docs/preview/website/src/content/docs/ja/integrations.mdx index 45feb41c..44d1b3e7 100644 --- a/docs/preview/website/src/content/docs/ja/integrations.mdx +++ b/docs/preview/website/src/content/docs/ja/integrations.mdx @@ -177,9 +177,7 @@ herdr integration install devin このフックは、Devin のセッション、プロンプト、ツール使用、許可、停止の各イベントからネイティブセッション識別を報告します。Devin のフックはすべての許可キャンセルやユーザー割り込みの後に信頼できる状態遷移を発行しないため、Devin の状態は引き続き Herdr のスクリーンマニフェストと OSC 検出から得られます。 -Linux と macOS では、Herdr はデフォルトで `~/.config/devin` を使い、`XDG_CONFIG_HOME` が設定されていれば `$XDG_CONFIG_HOME/devin` を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは `herdr-agent-state.sh` を書き込み、`config.json` に Herdr のフックエントリを追加します。フックは Devin の実行中にセッション参照を更新します。アンインストールは `config.json` から Herdr のエントリを削除し、フックスクリプトを削除します。 - -Devin インテグレーションのインストールは、現在 Windows ではサポートされていません。Devin の Windows 設定は `%APPDATA%\devin` に保存されますが、Herdr はまだその場所を解決できません。フックがなくても、ネイティブプロセス検出とスクリーン検出は動作します。 +`XDG_CONFIG_HOME` が設定されていれば、Herdr は `$XDG_CONFIG_HOME/devin` を使います。それ以外では、Linux と macOS では `~/.config/devin`、Windows では `%APPDATA%\devin` を使います。Devin の設定ディレクトリはあらかじめ存在している必要があります。インストールは Unix では `herdr-agent-state.sh`、Windows では `herdr-agent-state.ps1` を書き込み、`config.json` に Herdr のフックエントリを追加します。フックは Devin の実行中にセッション参照を更新します。アンインストールは `config.json` から Herdr のエントリを削除し、フックスクリプトを削除します。 Herdr は保存された Devin セッションを `devin --resume <id>` で resume します。フックのインストール有無にかかわらず、スクリーンマニフェスト検出が状態の権威のままです。 diff --git a/docs/preview/website/src/content/docs/ja/persistence-remote.mdx b/docs/preview/website/src/content/docs/ja/persistence-remote.mdx index 266d407b..b83c3b89 100644 --- a/docs/preview/website/src/content/docs/ja/persistence-remote.mdx +++ b/docs/preview/website/src/content/docs/ja/persistence-remote.mdx @@ -35,6 +35,43 @@ herdr session stop work --json herdr session delete side-project --json ``` +## 保存済み SSH マシン + +よく使う接続先を保存すると、1 つの Herdr クライアントから複数のマシンで作業できます: + +```bash +herdr machine add workbox --label "Build machine" --remote-session agents +herdr machine add ssh://you@server:2222 --label "Production" --remote-session operations +herdr machine list +``` + +`machine add` はリモートマシンに Herdr を準備し、指定したセッションのバックグラウンドサーバーを起動してからプロファイルを保存します。インストール済みバイナリとは別に実行中のサーバーを確認し、クライアントとリリースバージョンが異なっていても、互換性があればそのまま使用します。実行中のサーバーに更新が必要な場合、対応していればライブハンドオフでペインのプロセスを維持します。対応していなければ、サーバーを停止する前に確認します。Herdr が未インストールまたは非互換の場合は、`--remote` と同じ承認付きのセットアップを行います。承認が必要な場合は対話型ターミナルで実行してください。キャンセルするとプロファイルは保存されません。セットアップ終了後もリモートサーバーは動き続けます。 + +保存済みマシンの変更は、開いているローカルの Herdr クライアントに通常 1 秒以内に自動反映されます。マシンの切り替え中の場合は、切り替えが完了してから反映します。追加または有効化した SSH マシンはサイドバーに Local と並んで表示され、選択を変えずにバックグラウンドで接続します。マシンまたはそのワークスペースを選ぶと切り替わります。接続中のマシンのメタデータ、エージェント状態、通知は引き続き利用できますが、ペイン画面、入力、表示領域、グラフィックスのやり取りは選択中のマシンだけに限定されます。2 つのサーバーが同じ内部 ID を使っていても、ワークスペース、タブ、ペイン、エージェント、グラフィックスの識別情報はマシンごとに分離されます。 + +起動時は保存済み SSH マシンを待たず、接続バッジも表示せずに Local を開きます。有効な保存済みマシンがあれば、Local への接続に失敗してもクライアントを開けます。Local の停止や再起動で正常な SSH 接続が閉じることはありません。Local のサーバーが戻ると、使用中のマシンから選択を奪わずに再接続します。応答しないマシンが、別のマシンへの入力や接続処理を妨げることはありません。 + +Herdr は接続中の SSH マシンのアプリケーションレベルの通信を監視し、通信がない間は軽量なヘルスチェックを行います。Local ではリモート用のヘルスチェックを使わず、接続の終了や失敗で切断を検知します。スリープ、ネットワークの中断、SSH の障害などで接続が不健全になると Reconnecting と表示し、上限のある待機間隔で再試行します。最後のワークスペース、エージェント、選択中のペインの状態は暗く表示されたまま固定され、新しい接続と整合した画面が届くまで入力やその状態への移動は無効になります。再接続がプロンプトに回答したり、リモートサーバーのインストール、更新、再起動、ハンドオフを行ったりすることはありません。ホスト鍵の承認、認証、互換性のある Herdr のインストールが必要な接続先は Attention と表示され、Local とほかのマシンはそのまま使えます。プロファイルに対応する単独接続用のコマンドをターミナルで実行してセットアップを完了してください。例: + +```bash +herdr --remote workbox --session agents --handoff +``` + +Attention と表示されている場合は、セットアップ後にクライアントを再起動して接続を再試行してください。名前の変更、無効化、削除にはプロファイルの不透明な ID を使います: + +```bash +herdr machine rename <profile-id> --label "New name" +herdr machine disable <profile-id> +herdr machine enable <profile-id> +herdr machine remove <profile-id> +``` + +名前の変更はラベルだけを更新し、再接続しません。削除または無効化すると、クライアントからそのマシンだけを切断します。マシンに到達できなくても削除でき、リモートセッションは動き続けます。表示中のマシンを削除または無効化すると Local に戻ります。Local が利用できない場合は、別のリモートを選ぶのではなく、利用不可と表示して再接続します。保存済みマシンのファイルが読めない、または不正な場合は、現在の接続を変更せずに通知を表示し、自動で読み込みを再試行します。 + +保存するのは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態だけです。パスワード、秘密鍵、エージェントのチケット、SSH 制御ソケットをマシンカタログに保存することはありません。 + +クライアントはデフォルトでローカルのキーバインドを使います。選択中のマシンが公開するカスタムコマンドは、そのマシンで実行されます。Herdr はローカルのコマンドプラグイン、設定、実行ファイル、シークレットを SSH ホストにコピーしません。リモートに必要なコマンドやプラグインがなければ、エラーを表示します。 + ## SSH 越しのリモートアタッチ リモートモードは 2 つあり、[Herdr での作業の進め方](/ja/docs/how-to-work/)で比較しています。tmux スタイルの方法では、サーバーに SSH してそこで `herdr` を実行します。もうひとつは、ローカルマシンから SSH 越しにアタッチする方法です: @@ -118,13 +155,3 @@ herdr terminal attach term_abc123 ```bash herdr terminal attach term_abc123 --takeover ``` - -## シングルプロセスの逃げ道 - -バックグラウンドのサーバー/クライアント分離なしで Herdr を実行するには `--no-session` を使います: - -```bash -herdr --no-session -``` - -これは主にデバッグや互換性のための逃げ道です。デフォルトの永続セッションモードが通常の使い方です。 diff --git a/docs/preview/website/src/content/docs/ja/session-state.mdx b/docs/preview/website/src/content/docs/ja/session-state.mdx index 6f3753f0..eaf78da4 100644 --- a/docs/preview/website/src/content/docs/ja/session-state.mdx +++ b/docs/preview/website/src/content/docs/ja/session-state.mdx @@ -103,6 +103,6 @@ herdr update --handoff herdr --remote workbox --handoff ``` -素の `herdr update` と素の `herdr --remote workbox` は、デフォルトでは通常の再起動/停止フローを使います。 +素の `herdr update` は新しいクライアントをインストールし、エンドポイント世代 1 のサーバーを動かしたままにします。素の `herdr --remote workbox` も、バージョンが違っていても互換性のあるリモートサーバーを動かしたままにします。停止が必要なのは世代 1 より前のサーバーを一度だけ更新するときです。対応する実行中サーバーをペインプロセスを失わず明示的に置き換えたい場合は `--handoff` を使います。 `herdr update --handoff` は Herdr 自身のアップデーターが管理するインストールにのみ適用されます。Homebrew、mise、Nix のインストールはそれぞれのパッケージマネージャーで更新されるため、そこでは `herdr update` は無効化されており、ライブハンドオフは実行できません。 diff --git a/docs/preview/website/src/content/docs/ja/socket-api.mdx b/docs/preview/website/src/content/docs/ja/socket-api.mdx index 5bb4fea7..8785cadd 100644 --- a/docs/preview/website/src/content/docs/ja/socket-api.mdx +++ b/docs/preview/website/src/content/docs/ja/socket-api.mdx @@ -145,9 +145,9 @@ CLI の `herdr api snapshot` は、クライアントやエージェントが簡 クライアントは `offset_from_bottom == 0` を最下部にいる状態として扱えます。 -### 実験的なペイングラフィックス +### ペイングラフィックス -ペイングラフィックスを使うと、プラグインがペイン上に画像データを配置できます。`[experimental].kitty_graphics = true` の場合にのみ利用でき、それ以外ではすべてのペイングラフィックスメソッドが `feature_disabled` を返します。`pane.graphics.info` はグラフィックスレイヤーを作成せず、接続中クライアントのセルの幅と高さをピクセル単位で返します。`pane.graphics.set` は `data_base64` の `png`、`rgb`、`rgba` データを受け取り、`pane.graphics.clear` はレイヤーを削除します。 +ペイングラフィックスを使うと、プラグインがペイン上に画像データを配置できます。デフォルトで利用でき、サーバーで `[terminal].kitty_graphics = false` が設定されている場合は、すべてのペイングラフィックスメソッドが `feature_disabled` を返します。この設定の変更にはサーバーの再起動が必要です。`pane.graphics.info` はグラフィックスレイヤーを作成せず、接続中クライアントのセルの幅と高さをピクセル単位で返します。`pane.graphics.set` は `data_base64` の `png`、`rgb`、`rgba` データを受け取り、`pane.graphics.clear` はレイヤーを削除します。 ```json {"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}} @@ -749,6 +749,6 @@ herdr agent wait w1:p1 --until blocked ## プロトコルの安定性 -Herdr にはクライアント/サーバー互換性のためのプロトコルバージョンがあります。プロトコルの変更は、リリースの互換性を念頭にレビューされます。 +クライアント描画の Herdr UI は、ローカルサーバーと SSH サーバーに安定したエンドポイント世代を使います。クライアントとサーバーのビルドが一致する必要はありません。接続時にコアのスナップショット、画面、入力、blob コーデックを合意し、サーバーが対応 API メソッドを通知します。メソッドがない場合は、そのサーバー上の該当アクションだけを無効にしてクライアント側通知を表示します。拒否やタイムアウトも接続を終了せず通知します。エンドポイント世代 1 より前のサーバーだけは最後の 1 回の更新が必要です。 -新しい挙動に依存する前に、`ping` または `herdr status` でサーバーのプロトコルを確認してください。未知のフィールドは寛容に扱ってください。 +番号付きバイナリプロトコルは、直接ターミナル接続やライブハンドオフなど、同一インストール内の内部操作に残ります。異なるビルド間でそれらを使う前に `ping` または `herdr status` を確認してください。JSON API クライアントは未知のフィールドを無視し、未対応メソッドを通常のエラーとして扱う必要があります。 diff --git a/docs/preview/website/src/content/docs/ja/windows-beta.mdx b/docs/preview/website/src/content/docs/ja/windows-beta.mdx index 96c8e12f..7d51fe0d 100644 --- a/docs/preview/website/src/content/docs/ja/windows-beta.mdx +++ b/docs/preview/website/src/content/docs/ja/windows-beta.mdx @@ -21,7 +21,7 @@ curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del Windows ビルドは安定版とプレビューの両方のアップデートチャンネルで提供されます。新規インストールはデフォルトで安定版を使い、通常の利用には安定版を推奨します。既存のプレビューインストールは、`herdr channel set stable` を実行するまでプレビューに残ります。古いプレビュービルドでこのコマンドが拒否される場合は、プレビューのまま一度 `herdr update` を実行してから再試行してください。プレビューでは `master` からの新しく検証の少ない修正を受け取れますが、リグレッションが起きる可能性があります。そのトレードオフを望む場合に限り、`herdr channel set preview` でオプトインしてください。 -インストーラーはリリースを `%USERPROFILE%\.herdr\packages\standalone\releases` に保存し、`%LOCALAPPDATA%\Programs\Herdr\bin` を現在のリリースに向け、実行中のプロセスがアップデートを妨げないよう少数の古いリリースを保持します。 +インストーラーはリリースを `%USERPROFILE%\.herdr\packages\standalone\releases` に保存し、有効なバージョン付きリリースディレクトリを PATH に追加し、`%LOCALAPPDATA%\Programs\Herdr\bin` を安定した互換エイリアスとして維持します。また、実行中のプロセスがアップデートを妨げないよう少数の古いリリースを保持します。 内部テスト向けに、`HERDR_MANIFEST_URL` でインストーラーを Herdr の安定版/プレビューマニフェストではなくカスタムマニフェストに向けられます。カスタムプレビューマニフェストでは `HERDR_CHANNEL=preview` も設定してください。 @@ -51,7 +51,7 @@ Windows ビルドは安定版とプレビューの両方のアップデートチ Windows のエージェントプロセス検出は、ペインのシェルの子孫プロセスをスキャンし、npm/Node や Git Bash のプロセスチェーンを含む直接のエージェントと一般的なコマンドラッパーを認識します。Git Bash から起動したエージェントはエミュレートされた `exec` 境界を越えて追跡されますが、Unix のフォアグラウンドプロセスグループ検出と同じものではありません。 -Windows でインテグレーションをインストールできるのは、現在 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI、Antigravity CLI です。利用可能な対象は Unix より少なく、インストール形式が Windows で未対応のインテグレーションは表示されないか拒否されます。Devin CLI のプロセス検出とスクリーン検出は Windows でも動作しますが、オプションのセッション識別フックは現在インストールできません。 +Windows でインテグレーションをインストールできるのは、現在 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI、Antigravity CLI です。利用可能な対象は Unix より少なく、インストール形式が Windows で未対応のインテグレーションは表示されないか拒否されます。 プラグインは、プレビューとしてマニフェストのプラットフォームに `windows` をサポートします。GitHub インストール、ローカルリンク、ビルドコマンド、アクション、イベント、プラグインペインは Windows ではベストエフォートです。コマンドは argv 形式で Windows 互換である必要があります。`npm`、`bun`、`node` のような Node パッケージの shim は `PATH` にあれば動作するはずですが、`sh` や Bash を使う Unix 専用の例には Windows 向けの代替が必要です。プラットフォームフィルターは、未サポートのビルドコマンドをスキップし、未サポートのアクションやペインには `platform_unsupported` を返します。 @@ -82,7 +82,7 @@ switch_ascii_input_source_in_prefix = true Windows 上の一部のエージェントは `ctrl+v` を受け取り、クリップボード画像を直接読み取れます。Herdr 自身のクリップボード画像リーダーはローカルのネイティブ Windows ペインには配線されていないため、エージェント自身による画像貼り付けはターミナルとエージェントに依存します。`alt+v` などエージェントの画像貼り付けショートカットによって、Herdr が管理するローカルクリップボードブリッジが追加されるわけではありません。リモートクリップボード画像ブリッジは、Linux/macOS ホストへの `herdr --remote` で別途サポートされます。 -Kitty graphics は実験的機能で、外側のターミナルに依存します。`experimental.kitty_graphics = true` の場合、Herdr は他のプラットフォームと同様に Windows でも Kitty graphics protocol の出力を送ります。この経路は Windows の WezTerm から WSL 内の Herdr をホストする構成で動作確認されていますが、ネイティブ Windows のターミナルと ConPTY の組み合わせはすべて検証済みではありません。Windows Terminal は Herdr が使う Kitty graphics 経路を提供しません。外側のターミナルが Kitty graphics に対応しており、その組み合わせをテストする場合を除いて、このオプションは無効のままにしてください。 +Kitty graphics はデフォルトで有効で、外側のターミナルに依存します。Herdr は他のプラットフォームと同様に Windows でも Kitty graphics protocol の出力を送ります。この経路は Windows の WezTerm から WSL 内の Herdr をホストする構成で動作確認されていますが、ネイティブ Windows のターミナルと ConPTY の組み合わせはすべて検証済みではありません。Windows Terminal は Herdr が使う Kitty graphics 経路を提供しません。外側のターミナルがグラフィックス出力を正しく扱えない場合は、`[terminal].kitty_graphics = false` に設定してください。 ## 既知の注意点 @@ -133,7 +133,7 @@ herdr --remote workbox 接続先ホストは Linux または macOS である必要があります。Herdr はインストール済みの Windows OpenSSH クライアントと SSH 設定を使います。Windows OpenSSH では Herdr の Unix コントロールソケットによる接続再利用を使わないため、セットアップ中の繰り返しプロンプトを避けるには Windows の `ssh-agent` による鍵認証を推奨します。 -Windows のアップデートは Windows インストーラー経由で行われ、バージョン付きインストールジャンクションを更新します。アップデート後は実行中の Herdr セッションを再起動してください。ライブハンドオフは Unix 専用です。 +Windows のアップデートは Windows インストーラー経由で行われ、有効なバージョン付きリリースパスを更新します。新しいターミナルまたは再接続した SSH セッションはそのパスを受け取るため、そこで Herdr を起動すると更新済みクライアントを使えます。互換性のある実行中サーバーはペインを動かしたままにします。新しいリリースのサーバー側変更が必要になったときだけ、後からサーバーを再起動してください。ライブハンドオフは Unix 専用です。 ## Windows の問題を報告する diff --git a/docs/preview/website/src/content/docs/persistence-remote.mdx b/docs/preview/website/src/content/docs/persistence-remote.mdx index 5044c66d..e5cec116 100644 --- a/docs/preview/website/src/content/docs/persistence-remote.mdx +++ b/docs/preview/website/src/content/docs/persistence-remote.mdx @@ -35,9 +35,46 @@ herdr session stop work --json herdr session delete side-project --json ``` +## Saved SSH machines + +Save repeat targets to work across several machines from one Herdr client: + +```bash +herdr machine add workbox --label "Build machine" --remote-session agents +herdr machine add ssh://you@server:2222 --label "Production" --remote-session operations +herdr machine list +``` + +`machine add` prepares Herdr on the remote machine and starts the requested session's background server before saving the profile. It checks the running server separately from the installed binary and keeps compatible servers, even when their release versions differ from your client. If the running server needs an upgrade, setup uses live handoff when supported to preserve pane processes; otherwise it asks before stopping the server. Missing or incompatible installations use the same approval-based setup as `--remote`; run the command in an interactive terminal when approval is needed. Cancelling setup leaves the profile unsaved. The remote server keeps running after setup exits. + +Saved-machine changes apply to open local Herdr clients automatically, normally within a second. An in-progress machine switch finishes before the change is applied. Added or enabled SSH machines appear with Local in the machine sidebar and connect in the background without changing your selection. Select a machine or one of its workspaces to switch to it. Herdr keeps metadata, agent state, and notifications from connected machines available, but streams pane surfaces, input, geometry, and graphics only for the selected machine. Workspace, tab, pane, agent, and graphics identities stay scoped to their machine even when two servers happen to use the same internal ID. + +Local opens directly on startup, without waiting for saved SSH machines or showing a connection badge. With enabled saved machines, the client can also open if Local actually fails, and stopping or restarting Local does not close healthy SSH connections. Local reconnects when its server returns, without taking selection away from the machine you are using. A stalled machine cannot block another machine's input or connection handling. + +Herdr checks connected SSH machines for application-level activity and uses a lightweight health probe while they are quiet. Local relies on its native connection closing or failing, not remote health probes. After sleep, a network interruption, or SSH failure, an unhealthy machine changes to Reconnecting and retries with bounded backoff. Its last workspace, agent, and selected pane state remains visible but dimmed and frozen; input and navigation into that cached state stay disabled until a fresh connection and coherent surface arrive. Reconnects never answer prompts or install, update, restart, or hand off a remote server. A target that needs host-key approval, authentication, or a compatible Herdr install shows Attention while Local and other machines keep working. Run the profile's explicit standalone command in a terminal to finish setup, for example: + +```bash +herdr --remote workbox --session agents --handoff +``` + +If the machine shows Attention, restart the client after setup to retry its connection. Rename, disable, or remove profiles by their opaque ID: + +```bash +herdr machine rename <profile-id> --label "New name" +herdr machine disable <profile-id> +herdr machine enable <profile-id> +herdr machine remove <profile-id> +``` + +Renaming updates the label without reconnecting. Removing or disabling a machine disconnects only that machine from the client; its remote sessions keep running, even if the machine is unreachable. If you remove or disable the machine you are viewing, the client returns to Local. If Local is unavailable, it shows that and reconnects rather than selecting another remote. An unreadable or invalid saved-machine file leaves current connections unchanged and shows a notice; the client retries reading it automatically. + +Saved profiles contain only the opaque ID, label, SSH target, explicit remote session, and enabled state. Passwords, private keys, agent tickets, and SSH control sockets are never stored in the machine catalog. + +The client uses local keybindings by default. Custom commands advertised by the selected machine still execute on that machine. Herdr does not copy local command plugins, configuration, executables, or secrets to SSH hosts; a missing remote command or plugin fails visibly. + ## Remote attach over SSH -Herdr supports two remote modes. [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path, or attach through SSH from your local machine: +Herdr supports two remote modes. [How to work with Herdr](/docs/how-to-work/) compares them. SSH to the server and run `herdr` there for the tmux-style path, use saved SSH machines for persistent multi-machine work, or attach through SSH from your local machine: ```bash herdr --remote workbox @@ -63,7 +100,7 @@ Then attach with: herdr --remote workbox ``` -Remote attach supports Linux, macOS, and Windows local clients connecting to Linux or macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a matching `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. If no matching binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install. Windows is not supported as the remote host. +Remote attach supports Linux, macOS, and Windows local clients connecting to Linux or macOS hosts on x86_64 and aarch64. Herdr checks the remote platform, prefers a compatible `herdr` already on the remote `PATH`, then checks common direct, Homebrew, mise, and Nix profile install paths. Local and remote versions do not need to match once both support the stable endpoint generation. If no compatible binary exists, interactive runs prompt to install one to `~/.local/bin/herdr`; non-interactive runs fail instead of modifying the host. If `~/.local/bin` is not on the remote `PATH`, Herdr warns after install. Windows is not supported as the remote host. By default, `herdr --remote` runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings. Existing user keepalive settings win. Linux and macOS clients also use a private per-attach control socket for connection reuse; Windows OpenSSH does not. Set `[remote].manage_ssh_config = false` to use plain `ssh` without Herdr's generated config or control socket. @@ -76,7 +113,7 @@ herdr --remote workbox For any remote authentication failure, verify plain SSH access first with `ssh workbox`, then run `herdr --remote workbox` again. -By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into experimental live handoff for a supported running remote server, pass `--handoff`: +A version difference alone does not replace or restart a running remote server. Remote attach uses the restart/stop flow only for a server that predates the stable endpoint generation or the detached-daemon baseline. To opt into experimental live handoff when that one-time upgrade is needed, pass `--handoff`: ```bash herdr --remote workbox --handoff @@ -151,13 +188,3 @@ newline-delimited JSON commands on stdin. `terminal.input` sends text or base64 bytes, `terminal.resize` changes the controller viewport, `terminal.scroll` scrolls the attached viewport, and `terminal.release` closes the controller. Only one controller owns input and resize at a time. - -## Single-process escape hatch - -Use `--no-session` to run Herdr without the background server/client split: - -```bash -herdr --no-session -``` - -Use `--no-session` mainly for debugging or compatibility. Persistent session mode remains the default. diff --git a/docs/preview/website/src/content/docs/session-state.mdx b/docs/preview/website/src/content/docs/session-state.mdx index f6d1b95e..ed147193 100644 --- a/docs/preview/website/src/content/docs/session-state.mdx +++ b/docs/preview/website/src/content/docs/session-state.mdx @@ -103,6 +103,6 @@ herdr update --handoff herdr --remote workbox --handoff ``` -Plain `herdr update` and plain `herdr --remote workbox` use the normal restart/stop flow by default. +Plain `herdr update` installs the new client and keeps endpoint-generation-1 servers running. Plain `herdr --remote workbox` also keeps a compatible remote server running across version differences. A stop is required only for the one-time upgrade from a pre-generation-1 server; use `--handoff` when you explicitly want to replace a supported running server without losing its pane processes. `herdr update --handoff` only applies to installs managed by Herdr's own updater. Homebrew, mise, and Nix installs are updated through their package managers, so `herdr update` is disabled there and cannot perform live handoff. diff --git a/docs/preview/website/src/content/docs/socket-api.mdx b/docs/preview/website/src/content/docs/socket-api.mdx index 8a055a36..13a71abb 100644 --- a/docs/preview/website/src/content/docs/socket-api.mdx +++ b/docs/preview/website/src/content/docs/socket-api.mdx @@ -175,11 +175,12 @@ pane. Clients can treat `offset_from_bottom == 0` as at-bottom state. -### Experimental pane graphics +### Pane graphics -Pane graphics let a plugin place image data over a pane. They are available -only when `[experimental].kitty_graphics = true`; otherwise every pane graphics -method returns `feature_disabled`. Calling `pane.graphics.info` explicitly +Pane graphics let a plugin place image data over a pane. They are available by +default; when the server has `[terminal].kitty_graphics = false`, every pane +graphics method returns `feature_disabled`. Changing this setting requires a +server restart. Calling `pane.graphics.info` explicitly activates capability discovery and returns the attached client's cell size, file-frame options, pixel-mouse support, the 16-layer limit, and `pane_visible`. `pane_visible` is true only when the target is in the active workspace and tab @@ -191,8 +192,8 @@ layers are placed in stable `(z_index, layer_id)` order. Each stream exclusively closing it removes that layer. Inline frames accept `png`, `rgb`, `rgba`, or `bgra`; BGRA is normalized once to owned RGBA. Herdr advances the host cache one image transaction per render pass, so arbitrary layer sets progress without -an aggregate frame. Headless transport keeps each transaction within its 32 MiB -wire limit; local monolithic rendering does not apply that transport limit. +an aggregate frame. Client transport keeps each transaction within its 32 MiB +wire limit. ```json {"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}} @@ -219,8 +220,8 @@ inline. Herdr replies with a `pane_graphics_frame_ack` only after the terminal accepts the file, or after a safe owned inline fallback is installed. Confirmed file-transport failure disables direct files for that client connection without disabling exact pixel mouse. A timeout or client loss closes the stream without -acknowledging source reuse. Monolithic `--no-session` mode advertises neither -fast file transport nor exact pixel mouse and remains on owned inline fallback. +acknowledging source reuse. Clients that cannot negotiate direct file transport +remain on the owned inline fallback. Direct files are always complete canonical `width * height * 4` RGBA frames. `file_frame_max_bytes` is the limit that remains eligible for owned inline fallback. @@ -934,7 +935,18 @@ Errors look like this: ## Protocol stability -Herdr has a protocol version for client/server compatibility. Protocol changes -are reviewed for release compatibility. - -Check the server protocol with `ping` or `herdr status` before depending on new behavior. Handle unknown fields gracefully. +The client-rendered Herdr UI uses a stable endpoint generation for local and SSH +servers. Client and server builds do not need to match. During connection setup, +they agree on the core snapshot, screen, input, and blob codecs, and the server advertises +the API methods and optional capabilities it supports. Saved SSH federation requires the +`surface_interest` capability so only the selected machine streams a pane surface and the +`health_check` capability so a quiet broken connection cannot remain Online indefinitely. A server +without this lifecycle support stays at Attention until it is explicitly updated. Other missing methods disable +only those actions and show a client-local notice; they do not disconnect the UI. Rejected +or timed-out actions are also reported without ending the connection. Servers +from before endpoint generation 1 need one final update. + +The numbered binary protocol remains for same-install and internal operations, +including direct terminal attach and live handoff. Check `ping` or `herdr status` +before using those operations across different builds. JSON API clients should +ignore unknown fields and handle unsupported methods as normal errors. diff --git a/docs/preview/website/src/content/docs/troubleshooting.mdx b/docs/preview/website/src/content/docs/troubleshooting.mdx index 4c889c32..69e65110 100644 --- a/docs/preview/website/src/content/docs/troubleshooting.mdx +++ b/docs/preview/website/src/content/docs/troubleshooting.mdx @@ -61,7 +61,7 @@ Herdr deliberately does not rewrite modified arrows because terminal application ## Herdr updated, but the running session is still old -Updating the binary does not always replace a compatible server that is already running. Check `herdr status`. To start the updated server, stop the session and launch Herdr again: +Updating the binary does not replace a compatible server that is already running. Start Herdr again to use the updated client. If you also need server-side changes from the release, check `herdr status`, then stop the session and launch Herdr again: ```bash herdr server stop diff --git a/docs/preview/website/src/content/docs/windows-beta.mdx b/docs/preview/website/src/content/docs/windows-beta.mdx index ed21feeb..255727a2 100644 --- a/docs/preview/website/src/content/docs/windows-beta.mdx +++ b/docs/preview/website/src/content/docs/windows-beta.mdx @@ -21,7 +21,7 @@ curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del Windows builds are available through both stable and preview update channels. New installs use stable by default, and stable is recommended for normal use. Existing preview installs stay on preview until you run `herdr channel set stable`. If an older preview build rejects that command, run `herdr update` once on preview and retry. Preview provides newer, less-tested fixes from `master` and may regress; opt in with `herdr channel set preview` only when you want that tradeoff. -The installer stores releases under `%USERPROFILE%\.herdr\packages\standalone\releases`, points `%LOCALAPPDATA%\Programs\Herdr\bin` at the current release, and keeps a small number of older releases so running processes do not block updates. +The installer stores releases under `%USERPROFILE%\.herdr\packages\standalone\releases`, puts the active versioned release directory on PATH, keeps `%LOCALAPPDATA%\Programs\Herdr\bin` as a stable compatibility alias, and retains a small number of older releases so running processes do not block updates. For internal testing, `HERDR_MANIFEST_URL` can point the installer at a custom manifest instead of Herdr's stable or preview manifest. Set `HERDR_CHANNEL=preview` with a custom preview manifest. @@ -51,7 +51,7 @@ Local persistent sessions continue running after the client detaches or its term Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers, including npm/Node and Git Bash process chains. It follows Git Bash-launched agents across emulated `exec` boundaries, but it is not the same as Unix foreground process-group detection. -Windows integration installation currently supports Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Kilo Code CLI, Droid, Kimi Code CLI, Qoder CLI, and Antigravity CLI. Availability is narrower than on Unix; Herdr hides or rejects integrations whose install format is not supported on Windows. Devin CLI process and screen detection work on Windows, but its optional session-identity hook cannot currently be installed. +Windows integration installation currently supports Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, OpenCode, Kilo Code CLI, Droid, Kimi Code CLI, Qoder CLI, and Antigravity CLI. Availability is narrower than on Unix; Herdr hides or rejects integrations whose install format is not supported on Windows. Plugins support `windows` as a manifest platform in preview. GitHub install, local link, build commands, actions, events, and plugin panes are best-effort on Windows. Commands are argv commands and must be Windows-compatible; Node package shims such as `npm`, `bun`, and `node` are expected to work when they are on `PATH`, while Unix-only examples using `sh` or Bash need Windows-specific alternatives. Platform filters skip unsupported build commands and return `platform_unsupported` for unsupported actions or panes. @@ -82,7 +82,7 @@ Other Windows IMEs are not supported by this option yet. See [Configuration](/do Some Windows agents can receive `ctrl+v` and read clipboard images directly. Herdr's own clipboard-image reader is not wired into local native Windows panes, so agent-native image paste remains dependent on the terminal and agent. Agent image-paste shortcuts such as `alt+v` do not add a Herdr-managed local clipboard bridge. Remote clipboard image bridging is supported separately through `herdr --remote` to Linux and macOS hosts. -Kitty graphics is experimental and depends on the outer terminal. When `experimental.kitty_graphics = true`, Herdr emits Kitty graphics protocol output on Windows as it does on other platforms. This path has been exercised with Windows WezTerm hosting Herdr through WSL, but native Windows terminal and ConPTY combinations are not all verified. Windows Terminal does not expose the Kitty graphics path Herdr uses. Leave the option disabled unless the outer terminal supports Kitty graphics and you are testing that combination. +Kitty graphics is enabled by default and depends on the outer terminal. Herdr emits Kitty graphics protocol output on Windows as it does on other platforms. This path has been exercised with Windows WezTerm hosting Herdr through WSL, but native Windows terminal and ConPTY combinations are not all verified. Windows Terminal does not expose the Kitty graphics path Herdr uses. Set `[terminal].kitty_graphics = false` if the outer terminal mishandles graphics output. ## Known caveats @@ -133,7 +133,7 @@ herdr --remote workbox The target host must run Linux or macOS. Herdr uses the installed Windows OpenSSH client and your SSH configuration. Windows OpenSSH does not use Herdr's Unix control-socket reuse, so key authentication through Windows `ssh-agent` is recommended to avoid repeated prompts during remote setup. -Windows updates run through the Windows installer and update the versioned install junction. Restart running Herdr sessions after updating. Live handoff is Unix-only. +Windows updates run through the Windows installer and update the active versioned release path. New terminals and reconnected SSH sessions receive that path; start Herdr there to use the updated client. Compatible running servers keep their panes alive. Restart a server later only when you need server-side changes from the release. Live handoff is Unix-only. ## Reporting Windows issues diff --git a/docs/preview/website/src/content/docs/zh-cn/agent-automation.mdx b/docs/preview/website/src/content/docs/zh-cn/agent-automation.mdx index a5b7a754..e7fa68fc 100644 --- a/docs/preview/website/src/content/docs/zh-cn/agent-automation.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/agent-automation.mdx @@ -73,7 +73,7 @@ herdr agent rename w1:p2 reviewer 窗格输入直接指定终端,不关心当前进程。智能体输入会解析实时智能体;如果该智能体已不再控制此窗格,操作会被拒绝。 -除非智能体已经是 `blocked`,`agent prompt --wait` 会立即提交提示。已经是 `blocked` 时,它不会开始等待,而是返回 `agent_blocked`。已接受的提示从其他非 working 状态开始时,Herdr 首先要求在五秒内观察到生命周期变化。如果状态序列没有前进，它会返回 `agent_prompt_stalled`，而不是无限等待；调用方设置的 `--timeout` 不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。独立的 `agent wait` 会观察当前智能体；如果状态已经匹配，就会立即返回。两者默认匹配 `idle`、`done` 或 `blocked`。可以重复使用 `--until` 接受多个精确状态，例如 `--until idle --until done`；需要 `unknown` 时请明确使用 `--until unknown`。在 `agent prompt` 中，`--until` 必须与 `--wait` 一起使用。 +除非智能体已经是 `blocked`,`agent prompt --wait` 会立即提交提示。已经是 `blocked` 时,它不会开始等待,而是返回 `agent_blocked`。已接受的提示从其他非 working 状态开始时,Herdr 必须在五秒内观察到 `working` 或 `blocked`。如果没有观察到，Herdr 返回 `agent_prompt_stalled`；如果调用方的超时先到期，则返回普通的 `timeout` 错误。这可防止无关的 `idle`、`done` 或会话变化错误地完成等待。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。独立的 `agent wait` 会观察当前智能体；如果状态已经匹配，就会立即返回。两者默认匹配 `idle`、`done` 或 `blocked`。可以重复使用 `--until` 接受多个精确状态，例如 `--until idle --until done`；需要 `unknown` 时请明确使用 `--until unknown`。在 `agent prompt` 中，`--until` 必须与 `--wait` 一起使用。 `idle` 表示智能体正等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,但用于后台工作完成后,直到该标签页获得焦点或 `pane focus` / `agent focus` 指向它。仅通过 CLI 读取不会把它标记为已查看。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示智能体存在,但 Herdr 无法可靠判断其生命周期;它不代表工作成功完成。区别重要时,请指定精确的 `--until` 状态。 diff --git a/docs/preview/website/src/content/docs/zh-cn/cli-reference.mdx b/docs/preview/website/src/content/docs/zh-cn/cli-reference.mdx index b00ad592..874143d8 100644 --- a/docs/preview/website/src/content/docs/zh-cn/cli-reference.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/cli-reference.mdx @@ -15,7 +15,6 @@ herdr --session work # 启动或连接命名会话 herdr --remote workbox # 通过 SSH 连接,使用本地按键绑定 herdr --remote workbox --remote-keybindings server herdr --remote workbox --handoff -herdr --no-session # 单进程逃生舱 herdr --default-config # 打印默认配置 herdr update # 从配置的通道下载并安装 herdr update --handoff # 对受支持的运行中服务器启用实时交接 @@ -44,6 +43,23 @@ herdr api schema --output herdr-api.schema.json `herdr api schema` 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 `--json`;要写入文件则使用 `--output PATH`。 +## 已保存的 SSH 机器 + +```bash +herdr machine list [--json] +herdr machine add workbox --label "Build machine" [--remote-session agents] +herdr machine rename <profile-id> --label "New name" +herdr machine disable <profile-id> +herdr machine enable <profile-id> +herdr machine remove <profile-id> +``` + +`machine add` 会检查远程 Herdr 是否具备所需能力，仅在必要时征得批准后安装或更新，并在保存配置前启动指定会话的后台服务器。只要兼容，发行版本不必一致。需要批准安装或重启时，请在交互式终端中运行；设置失败或取消时不会保存配置。 + +更改会自动应用到已打开的本地 Herdr 客户端，通常在一秒内生效。新增或启用的机器在后台连接；重命名不会重新连接。移除或禁用只会断开该机器，远程会话仍会继续运行。移除正在查看的机器会返回 Local；如果 Local 不可用，则显示不可用状态，直到重新连接。每份配置在客户端状态文件中保存一个不透明 ID、标签、SSH 目标、明确的远程会话名和启用状态。Herdr 不保存密码、私钥或其他 SSH 凭据。 + +自动连接和重连均为非交互式。如果主机密钥、密码、密钥口令、MFA、安装、更新或重启需要批准，机器会显示 Attention，而不会打开隐藏的提示。请运行 Herdr 显示的独立连接命令，例如 `herdr --remote workbox --session agents --handoff`，在前台完成设置后重启客户端。 + ## Shell 补全 ```bash @@ -291,7 +307,7 @@ herdr agent explain --file PATH --agent LABEL [--json|--verbose] 成功的 start 只有在预期智能体占用同一终端并可接受交互输入后才返回。如果启动期间检测到 `blocked`,命令会立即返回 `agent_not_ready`。该名称仍可用于 `agent read` 和 `agent send-keys`,检测变为 `idle` 后即可用于发送提示。默认启动超时是 30000 毫秒;显式值必须大于 3000 且不超过 300000。 -`agent prompt` 遵循当前的 bracketed paste 模式,即使智能体处于 working 也会先发送文本,短暂延迟后再发送编码后的 Enter。如果智能体已经是 `blocked`,它不会发送输入,而是返回 `agent_blocked`。使用 `--wait` 时,从其他非 working 状态接受的提示必须在五秒内产生可观察的生命周期变化，否则 Herdr 返回 `agent_prompt_stalled`；调用方超时不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。`--until` 用于缩小匹配状态，不带 `--wait` 时会被拒绝。独立的 `agent wait` 在当前状态匹配时立即返回。两者默认匹配 `idle`、`done` 或 `blocked`；需要 `unknown` 时请明确使用 `--until unknown`。 +`agent prompt` 遵循当前的 bracketed paste 模式,即使智能体处于 working 也会先发送文本,短暂延迟后再发送编码后的 Enter。如果智能体已经是 `blocked`,它不会发送输入,而是返回 `agent_blocked`。使用 `--wait` 时,从其他非 working 状态接受的提示必须在五秒内产生可观察的 `working` 或 `blocked` 状态，否则 Herdr 返回 `agent_prompt_stalled`；如果调用方的超时先到期，则返回普通的 `timeout` 错误。这可防止无关的 `idle`、`done` 或会话变化错误地完成等待。观察到活动后，它会等待请求的第一个稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。`--until` 用于缩小匹配状态，不带 `--wait` 时会被拒绝。独立的 `agent wait` 在当前状态匹配时立即返回。两者默认匹配 `idle`、`done` 或 `blocked`；需要 `unknown` 时请明确使用 `--until unknown`。 `idle` 表示智能体在等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,用于未查看的后台工作完成后。聚焦该标签页或用 `pane focus` / `agent focus` 指向它会标记为已查看;仅通过 CLI 读取不会改变它。`blocked` 表示 Herdr 识别到审批或提问界面。`unknown` 表示智能体存在但无法可靠分类,不代表工作成功。 @@ -324,7 +340,7 @@ herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source `pane wait-output` 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制。`--match` 在单行中查找字面子串;`--regex` 使用 Rust 正则表达式语法并逐行匹配。 -`pane wait-output`、`agent wait` 和 `agent prompt --wait` 在省略 `--timeout` 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。 +`pane wait-output` 和 `agent wait` 在省略 `--timeout` 时会无限等待。对于 `agent prompt --wait`，观察到活动后，或提示开始时已处于 `working`，等待稳定状态的过程不会超时；如果提示从 non-working 状态开始且未观察到活动，五秒后仍会返回 `agent_prompt_stalled`。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。 ## 集成 diff --git a/docs/preview/website/src/content/docs/zh-cn/concepts.mdx b/docs/preview/website/src/content/docs/zh-cn/concepts.mdx index ab950416..5b5fefe5 100644 --- a/docs/preview/website/src/content/docs/zh-cn/concepts.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/concepts.mdx @@ -68,6 +68,8 @@ herdr session attach side-project 服务器拥有窗格和进程状态。客户端是连接到该服务器的终端 UI。 +只有一个客户端连接时,所有标签页会像以前一样采用该客户端的尺寸。连接多个客户端时,每个客户端都可以查看自己的工作区和标签页。不同标签页会分别采用查看它们的客户端尺寸;客户端查看同一标签页时,最后聚焦、选择或操作该标签页的客户端控制其中窗格的尺寸。 + 用 `ctrl+b q` 分离客户端。服务器和智能体会继续运行。 如果想结束会话并停止其中的窗格,停止服务器: diff --git a/docs/preview/website/src/content/docs/zh-cn/configuration.mdx b/docs/preview/website/src/content/docs/zh-cn/configuration.mdx index 46db8777..a4c1a338 100644 --- a/docs/preview/website/src/content/docs/zh-cn/configuration.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/configuration.mdx @@ -60,7 +60,7 @@ headless_cols = 160 headless_rows = 50 ``` -客户端连接后，其尺寸仍决定共享运行时的大小。客户端断开后，现有窗格 PTY 会保留上次连接时的尺寸，而新的无客户端布局会使用配置的回退值。 +只有一个客户端连接时,所有标签页都会采用它的尺寸。连接多个客户端时,每个正在查看的标签页会采用最后聚焦、选择或操作它的客户端尺寸。当只剩一个客户端时,所有标签页会立即恢复为该客户端的尺寸。没有客户端连接时,现有窗格 PTY 会保留最后的尺寸,新的无客户端布局会使用配置的回退值。 ## 终端默认值 @@ -348,7 +348,7 @@ status_indicators = "symbols" [ui.sidebar.agents] row_gap = 0 rows = [ - ["state_icon", "workspace", "tab"], + ["state_icon", "machine", "workspace", "tab"], ["agent"], ] @@ -364,6 +364,7 @@ Agent 行支持以下内置 token： - `state_icon` — 智能体语义状态的彩色图标。 - `state_text` — `idle`、`working`、`blocked`、`done` 或 `unknown`；如果报告中包含显示标签，也会一并显示。 +- `machine` — 客户端连接多台机器时显示机器标签；只有一台本地机器时省略。 - `workspace` — 工作区名称。 - `tab` — 标签页名称（如有）。 - `pane` — 窗格名称（如有）。 @@ -381,7 +382,7 @@ Space 行支持以下内置 token： - `git_status` — 非零时显示 Git ahead 和 behind 数量。 - `$name` — 名为 `name` 的自定义工作区元数据。 -token 会按配置顺序渲染。Herdr 通常使用 ` · ` 分隔相邻值，并在 `state_icon` 后使用一个空格。缺失值及其分隔符会消失；当一行中的所有 token 都没有值时，该行会消失。每个布局最多可包含 16 行，每行最多可包含 16 个 token。 +token 会按配置顺序渲染。Herdr 通常使用 ` · ` 分隔相邻值，并在 `state_icon` 后使用一个空格。缺失值及其分隔符会消失；当一行中的所有 token 都没有值时，该行会消失。已有的自定义行不会改变；如果希望在自定义的多机器布局中显示机器标识，请显式添加 `machine`。每个布局最多可包含 16 行，每行最多可包含 16 个 token。 也可以用内联样式表定义 token： @@ -484,14 +485,16 @@ claude = "on" ## Kitty graphics -面向已连接本地客户端的 Kitty graphics 渲染是一项实验性功能，默认禁用： +Herdr 默认在兼容的外层终端中渲染窗格图像。要禁用图形渲染和窗格图形 API，请设置： ```toml -[experimental] -kitty_graphics = true +[terminal] +kitty_graphics = false ``` -仅在测试终端图像行为时启用。 +为兼容现有配置，旧的 `experimental.kitty_graphics` 设置仍然可用。若两者同时设置，`terminal.kitty_graphics` 优先。 + +更改此设置后，需要重启受影响的 Herdr 服务器或重新连接客户端。在远程会话中，服务器端设置控制窗格图形解析和 API 可用性，本地客户端设置控制向外层终端输出图形。 ## 智能体会话恢复 diff --git a/docs/preview/website/src/content/docs/zh-cn/how-to-work.mdx b/docs/preview/website/src/content/docs/zh-cn/how-to-work.mdx index 0df1b87f..5f455a66 100644 --- a/docs/preview/website/src/content/docs/zh-cn/how-to-work.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/how-to-work.mdx @@ -100,4 +100,4 @@ herdr --remote workbox 本地工作用 `herdr`。想让 Herdr 在远程 shell 上表现得像 tmux,或者在用手机 SSH 客户端时,用 `ssh you@server` 再 `herdr`。想要一个连接远程会话的本地瘦客户端 (包括本地剪贴板图像粘贴桥接) 时,用 `herdr --remote <host>`。 -关于远程引导细节、命名远程会话、自定义二进制、直接终端附加和 `--no-session`,参见[持久化与远程访问](/zh-cn/docs/persistence-remote/)。 +关于远程引导细节、命名远程会话、自定义二进制和直接终端附加,参见[持久化与远程访问](/zh-cn/docs/persistence-remote/)。 diff --git a/docs/preview/website/src/content/docs/zh-cn/install.mdx b/docs/preview/website/src/content/docs/zh-cn/install.mdx index 0324d60b..8faba506 100644 --- a/docs/preview/website/src/content/docs/zh-cn/install.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/install.mdx @@ -25,7 +25,7 @@ powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd ``` -安装器会下载适合你平台的发布二进制文件并放到 PATH 上。新的直接安装默认使用稳定更新通道。现有的 Windows 预览安装会继续留在预览通道,直到你运行 `herdr channel set stable`。Windows 安装器使用带版本号的安装文件夹,并更新一个 `current` 联接点,因此更新时不需要覆盖正在运行的 `herdr.exe`。 +安装器会下载适合你平台的发布二进制文件并放到 PATH 上。新的直接安装默认使用稳定更新通道。现有的 Windows 预览安装会继续留在预览通道,直到你运行 `herdr channel set stable`。在 Windows 上,PATH 指向当前带版本号的发布目录;安装器还会更新 `current` 和稳定的 `bin` 兼容别名,因此更新时不需要覆盖正在运行的 `herdr.exe`。 ## 用 Homebrew 安装 @@ -139,7 +139,7 @@ herdr channel set stable Windows 的常规使用建议选择稳定版。预览版能更早获得修复,但可能出现回归,因此只有在接受这一取舍时才应主动启用。现有的 Windows 预览安装会继续留在预览通道,直到你明确切换。如果旧预览构建拒绝 `herdr channel set stable`,请先在预览通道运行一次 `herdr update`,再重试切换通道。 -默认情况下,`herdr update` 安装新二进制文件,并不打扰兼容的运行中会话。如果某次更新改变了 Herdr 的客户端/服务器协议,Herdr 会在安装后询问是否停止旧服务器。要使用新版本,请停止旧服务器。停止会退出窗格进程。对于默认会话,运行 `herdr server stop`,再运行 `herdr`。对于命名会话,运行 `herdr session stop <name>`,再运行 `herdr session attach <name>`。 +默认情况下,`herdr update` 会安装新二进制文件,并让端点第 1 代服务器及其窗格进程继续运行。再次启动 Herdr 即可用更新后的客户端重新连接。纯客户端改动会立即生效。新的服务器端操作会保持不可用,直到对应服务器更新并重启;客户端会显示通知,而不会断开连接。只有早于端点第 1 代的服务器需要在更新时再停止最后一次。 要对受支持的运行中会话启用实验性的实时服务器交接,运行: @@ -147,7 +147,7 @@ Windows 的常规使用建议选择稳定版。预览版能更早获得修复, herdr update --handoff ``` -实时交接不适用于 Homebrew、mise 或 Nix 的包管理器更新。这些安装先用包管理器更新,然后在准备好使用新服务器时重启那个 Herdr 会话。如果运行中的会话仍在使用旧服务器,用 `herdr server stop` 或 `herdr session stop <name>` 停止它,再重新运行 Herdr。 +实时交接不适用于 Homebrew、mise 或 Nix 的包管理器更新。这些安装先用包管理器更新,再重新运行 Herdr,用更新后的客户端连接。兼容的旧服务器会继续运行。只有需要新版本的服务器端改动时,才稍后用 `herdr server stop` 或 `herdr session stop <name>` 重启它。 ## 系统要求 diff --git a/docs/preview/website/src/content/docs/zh-cn/integrations.mdx b/docs/preview/website/src/content/docs/zh-cn/integrations.mdx index 2d7ec99f..ea0fc3d3 100644 --- a/docs/preview/website/src/content/docs/zh-cn/integrations.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/integrations.mdx @@ -177,9 +177,7 @@ herdr integration install devin 该钩子从 Devin 的会话、提示、工具使用、权限和停止事件中上报原生会话身份。Devin 的状态仍来自 Herdr 的屏幕清单和 OSC 检测,因为 Devin 钩子不会在每次权限取消或用户中断后都发出可靠的状态转换。 -在 Linux 和 macOS 上,Herdr 默认使用 `~/.config/devin`,设置了 `XDG_CONFIG_HOME` 时使用 `$XDG_CONFIG_HOME/devin`。Devin 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `config.json` 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 `config.json` 中移除 Herdr 条目并删除钩子脚本。 - -Devin 集成目前不支持在 Windows 上安装。Devin 的 Windows 配置存放在 `%APPDATA%\devin`,Herdr 尚不能解析该位置。即使没有钩子,原生进程检测和屏幕检测仍然可用。 +设置了 `XDG_CONFIG_HOME` 时,Herdr 使用 `$XDG_CONFIG_HOME/devin`。否则,在 Linux 和 macOS 上使用 `~/.config/devin`,在 Windows 上使用 `%APPDATA%\devin`。Devin 配置目录必须已经存在。安装在 Unix 上写入 `herdr-agent-state.sh`,在 Windows 上写入 `herdr-agent-state.ps1`,并向 `config.json` 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 `config.json` 中移除 Herdr 条目并删除钩子脚本。 Herdr 用 `devin --resume <id>` 恢复保存的 Devin 会话。无论钩子是否安装,屏幕清单检测始终是状态权威。 diff --git a/docs/preview/website/src/content/docs/zh-cn/persistence-remote.mdx b/docs/preview/website/src/content/docs/zh-cn/persistence-remote.mdx index ba50130e..a89a8ea3 100644 --- a/docs/preview/website/src/content/docs/zh-cn/persistence-remote.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/persistence-remote.mdx @@ -35,6 +35,43 @@ herdr session stop work --json herdr session delete side-project --json ``` +## 已保存的 SSH 机器 + +保存常用目标后，即可从一个 Herdr 客户端跨多台机器工作： + +```bash +herdr machine add workbox --label "Build machine" --remote-session agents +herdr machine add ssh://you@server:2222 --label "Production" --remote-session operations +herdr machine list +``` + +`machine add` 会在远程机器上准备 Herdr，并在保存配置前启动指定会话的后台服务器。它会分别检查运行中的服务器和已安装的二进制文件；即使服务器的发行版本与客户端不同，只要兼容就会保留。如果运行中的服务器需要升级，设置过程会在支持时使用实时交接来保留窗格进程，否则会在停止服务器前询问。未安装或不兼容时，使用与 `--remote` 相同的批准流程；需要批准时请在交互式终端中运行。取消设置不会保存配置。设置退出后，远程服务器会继续运行。 + +已保存机器的更改会自动应用到已打开的本地 Herdr 客户端，通常在一秒内生效。如果正在切换机器，会等待切换完成再应用更改。新增或启用的 SSH 机器会与 Local 一起显示在机器侧边栏中，并在后台连接，不会改变当前选择。选择机器或其工作区即可切换。Herdr 保留已连接机器的元数据、agent 状态和通知，但只为选中的机器传输窗格画面、输入、显示区域和图形。即使两个服务器碰巧使用相同的内部 ID，工作区、标签页、窗格、agent 和图形的身份也始终按机器隔离。 + +启动时会直接打开 Local，不等待已保存的 SSH 机器，也不显示连接标记。有已启用的保存机器时，即使 Local 连接失败，客户端仍能打开。停止或重启 Local 不会关闭正常的 SSH 连接。Local 服务器恢复后会自动重连，不会从正在使用的机器抢走选择。无响应的机器不会阻塞其他机器的输入或连接处理。 + +Herdr 会监测已连接 SSH 机器的应用层活动，并在空闲时使用轻量健康探测。Local 依靠本地连接关闭或失败来判断断开，不使用远程健康探测。睡眠、网络中断或 SSH 故障后，不健康的机器会显示 Reconnecting，并以有上限的退避间隔重试。最后的工作区、agent 和选中窗格状态会保留，但变暗并冻结；在新连接和一致的画面到达前，无法输入或导航到这些缓存状态。重连不会回答提示，也不会安装、更新、重启或交接远程服务器。需要批准主机密钥、完成认证或安装兼容 Herdr 的目标会显示 Attention，Local 和其他机器仍可正常使用。请在终端中运行该配置对应的独立连接命令来完成设置，例如： + +```bash +herdr --remote workbox --session agents --handoff +``` + +如果机器显示 Attention，请在设置完成后重启客户端以重试连接。使用配置的不透明 ID 来重命名、禁用或移除： + +```bash +herdr machine rename <profile-id> --label "New name" +herdr machine disable <profile-id> +herdr machine enable <profile-id> +herdr machine remove <profile-id> +``` + +重命名只更新标签，不会重新连接。移除或禁用只会将该机器从客户端断开；即使机器无法访问也可操作，其远程会话仍会继续运行。如果移除或禁用正在查看的机器，客户端会返回 Local。如果 Local 不可用，会显示该状态并尝试重连，而不是选择另一台远程机器。保存机器的文件无法读取或内容无效时，当前连接保持不变，客户端会显示通知并自动重试读取。 + +保存的配置仅包含不透明 ID、标签、SSH 目标、明确的远程会话名和启用状态。密码、私钥、agent 票据和 SSH 控制套接字绝不会存入机器目录。 + +客户端默认使用本地按键绑定。选中机器公布的自定义命令仍在该机器上执行。Herdr 不会将本地命令插件、配置、可执行文件或机密复制到 SSH 主机；远程缺少命令或插件时会明确报错。 + ## 通过 SSH 远程连接 远程模式有两种;[使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/)对它们做了比较。tmux 风格的路径是 SSH 到服务器并在那里运行 `herdr`。另一种是从本地机器通过 SSH 连接: @@ -118,13 +155,3 @@ herdr terminal attach term_abc123 ```bash herdr terminal attach term_abc123 --takeover ``` - -## 单进程逃生舱 - -用 `--no-session` 在没有后台服务器/客户端分离的情况下运行 Herdr: - -```bash -herdr --no-session -``` - -这主要是调试或兼容性的逃生舱。默认的持久会话模式才是常规路径。 diff --git a/docs/preview/website/src/content/docs/zh-cn/session-state.mdx b/docs/preview/website/src/content/docs/zh-cn/session-state.mdx index 0a0936ad..c046a3d4 100644 --- a/docs/preview/website/src/content/docs/zh-cn/session-state.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/session-state.mdx @@ -103,6 +103,6 @@ herdr update --handoff herdr --remote workbox --handoff ``` -普通的 `herdr update` 和普通的 `herdr --remote workbox` 默认使用常规的重启/停止流程。 +普通的 `herdr update` 会安装新客户端,并让端点第 1 代服务器继续运行。普通的 `herdr --remote workbox` 也会在版本不同时保留兼容的远程服务器。只有从早于第 1 代的服务器做一次性升级时才需要停止;如果要在不结束窗格进程的情况下明确替换受支持的运行中服务器,请使用 `--handoff`。 `herdr update --handoff` 只适用于由 Herdr 自带更新器管理的安装。Homebrew、mise 和 Nix 安装通过各自的包管理器更新,因此那些安装中 `herdr update` 被禁用,无法执行实时交接。 diff --git a/docs/preview/website/src/content/docs/zh-cn/socket-api.mdx b/docs/preview/website/src/content/docs/zh-cn/socket-api.mdx index ace5ba70..fb70287c 100644 --- a/docs/preview/website/src/content/docs/zh-cn/socket-api.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/socket-api.mdx @@ -145,9 +145,9 @@ CLI 的 `herdr api snapshot` 会把当前 `session.snapshot` 响应输出为 JSO 客户端可以把 `offset_from_bottom == 0` 视为位于底部。 -### 实验性窗格图形 +### 窗格图形 -窗格图形允许插件在窗格上放置图像数据。它们只在 `[experimental].kitty_graphics = true` 时可用;否则所有窗格图形方法都返回 `feature_disabled`。调用 `pane.graphics.info` 会返回所连接客户端的单元格像素宽度和高度,但不会创建图形层。`pane.graphics.set` 接受 `data_base64` 中的 `png`、`rgb` 或 `rgba` 数据,`pane.graphics.clear` 删除该图层。 +窗格图形允许插件在窗格上放置图像数据。该功能默认可用；当服务器设置 `[terminal].kitty_graphics = false` 时，所有窗格图形方法都返回 `feature_disabled`。更改此设置需要重启服务器。调用 `pane.graphics.info` 会返回所连接客户端的单元格像素宽度和高度,但不会创建图形层。`pane.graphics.set` 接受 `data_base64` 中的 `png`、`rgb` 或 `rgba` 数据,`pane.graphics.clear` 删除该图层。 ```json {"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}} @@ -745,6 +745,6 @@ herdr agent wait w1:p1 --until blocked ## 协议稳定性 -Herdr 有一个用于客户端/服务器兼容性的协议版本。协议变更会在考虑发布兼容性的前提下进行评审。 +由客户端渲染的 Herdr UI 对本地和 SSH 服务器使用稳定的端点代数。客户端和服务器构建不必一致。连接时,双方会协商核心快照、屏幕、输入和 blob 编解码器,服务器则公布它支持的 API 方法。缺少方法时,只禁用该服务器上的对应操作并显示客户端本地通知;操作被拒绝或超时也不会断开连接。只有早于端点第 1 代的服务器需要最后更新一次。 -在依赖新行为之前,用 `ping` 或 `herdr status` 检查服务器协议。对未知字段做宽容处理。 +带编号的二进制协议仍用于同一安装内的内部操作,包括直接终端连接和实时交接。跨不同构建使用这些操作前,请检查 `ping` 或 `herdr status`。JSON API 客户端应忽略未知字段,并把不支持的方法当作普通错误处理。 diff --git a/docs/preview/website/src/content/docs/zh-cn/windows-beta.mdx b/docs/preview/website/src/content/docs/zh-cn/windows-beta.mdx index a22058ae..35b1ff33 100644 --- a/docs/preview/website/src/content/docs/zh-cn/windows-beta.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/windows-beta.mdx @@ -21,7 +21,7 @@ curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del Windows 构建同时通过稳定版和预览版更新通道提供。新安装默认使用稳定版,常规使用也建议选择稳定版。现有预览安装会继续留在预览通道,直到你运行 `herdr channel set stable`。如果旧预览构建拒绝该命令,请先在预览通道运行一次 `herdr update`,再重试。预览版会提供来自 `master` 的更新、测试较少的修复,也可能出现回归;只有在接受这一取舍时,才应通过 `herdr channel set preview` 主动启用。 -安装器将发布版本保存在 `%USERPROFILE%\.herdr\packages\standalone\releases` 下,让 `%LOCALAPPDATA%\Programs\Herdr\bin` 指向当前版本,并保留少量旧版本,以免运行中的进程阻塞更新。 +安装器将发布版本保存在 `%USERPROFILE%\.herdr\packages\standalone\releases` 下,把当前带版本号的发布目录加入 PATH,将 `%LOCALAPPDATA%\Programs\Herdr\bin` 保留为稳定的兼容别名,并保留少量旧版本,以免运行中的进程阻塞更新。 对于内部测试,`HERDR_MANIFEST_URL` 可以让安装器指向自定义清单,而不是 Herdr 的稳定或预览清单。使用自定义预览清单时还应设置 `HERDR_CHANNEL=preview`。 @@ -51,7 +51,7 @@ Windows 构建同时通过稳定版和预览版更新通道提供。新安装默 Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接运行的智能体和常见的命令包装器,包括 npm/Node 和 Git Bash 进程链。它会跨越模拟的 `exec` 边界跟踪从 Git Bash 启动的智能体,但这和 Unix 前台进程组检测不是一回事。 -Windows 目前支持安装 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI 和 Antigravity CLI 集成。可用范围比 Unix 更窄;安装格式不受 Windows 支持的集成会被隐藏或拒绝。Devin CLI 的进程检测和屏幕检测可在 Windows 上工作,但目前无法安装其可选的会话身份钩子。 +Windows 目前支持安装 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、OpenCode、Kilo Code CLI、Droid、Kimi Code CLI、Qoder CLI 和 Antigravity CLI 集成。可用范围比 Unix 更窄;安装格式不受 Windows 支持的集成会被隐藏或拒绝。 插件以预览状态支持在清单中声明 `windows` 平台。GitHub 安装、本地链接、构建命令、动作、事件和插件窗格在 Windows 上尽力而为。命令是 argv 命令,必须兼容 Windows;`npm`、`bun`、`node` 之类的 Node 包 shim 只要在 `PATH` 上就应该能用,而使用 `sh` 或 Bash 的 Unix 专用示例需要 Windows 专用的替代方案。平台过滤器会跳过不支持的构建命令,并对不支持的动作或窗格返回 `platform_unsupported`。 @@ -82,7 +82,7 @@ switch_ascii_input_source_in_prefix = true Windows 上的部分智能体可以接收 `ctrl+v` 并直接读取剪贴板图像。Herdr 自己的剪贴板图像读取器尚未接入本地原生 Windows 窗格,因此智能体原生图像粘贴仍取决于终端和智能体。`alt+v` 等智能体图像粘贴快捷键不会增加由 Herdr 管理的本地剪贴板桥。远程剪贴板图像桥通过连接 Linux/macOS 主机的 `herdr --remote` 单独受支持。 -Kitty graphics 是实验性功能,并取决于外层终端。设置 `experimental.kitty_graphics = true` 后,Herdr 会像在其他平台上一样在 Windows 上输出 Kitty graphics protocol。这个路径已在 Windows WezTerm 托管 WSL 中 Herdr 的配置下得到验证,但原生 Windows 的各种终端与 ConPTY 组合尚未全部验证。Windows Terminal 不提供 Herdr 使用的 Kitty graphics 路径。除非外层终端支持 Kitty graphics 且你正在测试该组合,否则请保持此选项禁用。 +Kitty graphics 默认启用，并取决于外层终端。Herdr 会像在其他平台上一样在 Windows 上输出 Kitty graphics protocol。这个路径已在 Windows WezTerm 托管 WSL 中 Herdr 的配置下得到验证，但原生 Windows 的各种终端与 ConPTY 组合尚未全部验证。Windows Terminal 不提供 Herdr 使用的 Kitty graphics 路径。如果外层终端无法正确处理图形输出，请设置 `[terminal].kitty_graphics = false`。 ## 已知注意事项 @@ -133,7 +133,7 @@ herdr --remote workbox 目标主机必须运行 Linux 或 macOS。Herdr 使用已安装的 Windows OpenSSH 客户端和你的 SSH 配置。Windows OpenSSH 不使用 Herdr 的 Unix control socket 连接复用,因此建议通过 Windows `ssh-agent` 使用密钥认证,避免远程设置期间重复提示。 -Windows 更新通过 Windows 安装器进行,并更新带版本号的安装联接点。更新后请重启运行中的 Herdr 会话。实时交接仅限 Unix。 +Windows 更新通过 Windows 安装器进行,并更新当前带版本号的发布路径。新终端和重新连接的 SSH 会话会获得该路径;在其中启动 Herdr 即可使用更新后的客户端。兼容的运行中服务器会让窗格继续运行。只有需要新版本的服务器端改动时,才稍后重启服务器。实时交接仅限 Unix。 ## 报告 Windows 问题 diff --git a/docs/preview/website/src/data/config-reference.json b/docs/preview/website/src/data/config-reference.json index 475c6a07..990509b2 100644 --- a/docs/preview/website/src/data/config-reference.json +++ b/docs/preview/website/src/data/config-reference.json @@ -434,6 +434,12 @@ "current", "path" ] + }, + { + "key": "terminal.kitty_graphics", + "type": "boolean", + "default": "true", + "description": "Render pane images in Kitty graphics-compatible outer terminals. Set false to disable graphics rendering and the pane graphics API. Restart the server or reattach the client after changing it. In remote sessions, server configuration controls parsing and API availability while local client configuration controls outer-terminal output." } ] }, @@ -575,7 +581,7 @@ "key": "keys.detach", "type": "keybinding", "default": "\"prefix+q\"", - "description": "Detach from server/client mode, or exit --no-session mode." + "description": "Detach the current client from its Herdr server." }, { "key": "keys.reload_config", @@ -1453,8 +1459,8 @@ { "key": "experimental.kitty_graphics", "type": "boolean", - "default": "false", - "description": "Experimental local Kitty graphics rendering for attached clients." + "default": "unset", + "description": "Deprecated compatibility key for terminal.kitty_graphics. Existing true and false values remain supported; terminal.kitty_graphics takes precedence when both are set." }, { "key": "experimental.pane_history", |