From 8256ce1cfa111896fb225f636375019e6b71bbfd Mon Sep 17 00:00:00 2001 From: kangal-bot <285672167+kangal-bot@users.noreply.github.com> Date: Tue, 29 Sep 2026 18:54:42 +0000 Subject: [PATCH] docs: publish preview documentation --- distribution/preview.json | 86 +++++++++-------- .../src/content/docs/add-herdr-support.mdx | 7 +- .../website/src/content/docs/agents.mdx | 87 ++++++++--------- .../src/content/docs/configuration.mdx | 2 +- .../website/src/content/docs/integrations.mdx | 13 +-- .../src/content/docs/ja/add-herdr-support.mdx | 7 +- .../src/content/docs/ja/agent-automation.mdx | 2 + .../website/src/content/docs/ja/agents.mdx | 93 ++++++++++--------- .../src/content/docs/ja/cli-reference.mdx | 5 +- .../src/content/docs/ja/configuration.mdx | 29 +++++- .../content/docs/ja/connecting-machines.mdx | 22 ++++- .../website/src/content/docs/ja/install.mdx | 2 + .../src/content/docs/ja/integrations.mdx | 15 +-- .../src/content/docs/ja/socket-api.mdx | 8 +- .../website/src/content/docs/socket-api.mdx | 2 +- .../content/docs/zh-cn/add-herdr-support.mdx | 7 +- .../content/docs/zh-cn/agent-automation.mdx | 2 + .../website/src/content/docs/zh-cn/agents.mdx | 93 ++++++++++--------- .../src/content/docs/zh-cn/cli-reference.mdx | 5 +- .../src/content/docs/zh-cn/configuration.mdx | 29 +++++- .../docs/zh-cn/connecting-machines.mdx | 22 ++++- .../src/content/docs/zh-cn/install.mdx | 2 + .../src/content/docs/zh-cn/integrations.mdx | 15 +-- .../src/content/docs/zh-cn/socket-api.mdx | 6 +- 24 files changed, 323 insertions(+), 238 deletions(-) diff --git a/distribution/preview.json b/distribution/preview.json index 56100919..e3579f97 100644 --- a/distribution/preview.json +++ b/distribution/preview.json @@ -1,37 +1,68 @@ { "schema_version": 1, "channel": "preview", - "base_version": "0.9.1", - "build_id": "2026-09-29-9dc3a1df2b56", - "commit": "9dc3a1df2b563df0637264fc0dffcd607c324ac5", - "built_at": "2026-09-29T11:55:31Z", + "base_version": "0.9.2", + "build_id": "2026-09-29-8e78f929d8f0", + "commit": "8e78f929d8f0306a5c68518969e90274c44cb1f0", + "built_at": "2026-09-29T18:25:31Z", "protocol": 22, "endpoint_generation": 1, - "notes": "Preview build 2026-09-29-9dc3a1df2b56\n\n[View changes](https://github.com/herdrdev/herdr/compare/80c0c07250d22f69d3fa05cb1700302d66180eb8...9dc3a1df2b563df0637264fc0dffcd607c324ac5)", + "notes": "Preview build 2026-09-29-8e78f929d8f0\n\n[View changes](https://github.com/herdrdev/herdr/compare/v0.9.2...8e78f929d8f0306a5c68518969e90274c44cb1f0)", "assets": { "linux-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-9dc3a1df2b56/herdr-linux-x86_64", - "sha256": "e550b8b82c0ace119426b1f1c80350314404c447a1e412b160b6ef5e0aa014e6" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-linux-x86_64", + "sha256": "6f3dffff0c9805e414ff9285c0a5ce8ff8bd1c0118383360048837baad8ad6f5" }, "linux-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-9dc3a1df2b56/herdr-linux-aarch64", - "sha256": "c0d0c97ccf181e68284382b56061785ef8fc483687ffacb9e77ef19cf0275bcb" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-linux-aarch64", + "sha256": "f26292297337d1b54dc9d1f01e473d4c95d572410577aac70534a69bb9123b91" }, "macos-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-9dc3a1df2b56/herdr-macos-x86_64", - "sha256": "a73ffb9f42631561dcd61dc882ca69db19a73cdec59ac9d2ba553229de255b12" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-macos-x86_64", + "sha256": "7cdf43b44cb4c0731a98932aeabe992e75781f4eead337bc52aa6889eff188ff" }, "macos-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-9dc3a1df2b56/herdr-macos-aarch64", - "sha256": "14f32140cdac41d0c7339bbe348e8e97bb7c70450e9686af30bf5a0b058e8628" + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-macos-aarch64", + "sha256": "7ebb310f974eaac7e45e9a46db470de11b24050dd929314757c952459bceaf3f" }, "windows-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-9dc3a1df2b56/herdr-windows-x86_64.zip", - "sha256": "09f37d09134dc9d1da34017dc27bb514552c692ff2355e7e16a87727d61f4745", + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-windows-x86_64.zip", + "sha256": "bbebbd192fc6356228efdfb89ad1ce86813f3aff41ad48dbf5082fbe94e2485c", "format": "zip" } }, "builds": { + "2026-09-29-8e78f929d8f0": { + "base_version": "0.9.2", + "commit": "8e78f929d8f0306a5c68518969e90274c44cb1f0", + "built_at": "2026-09-29T18:25:31Z", + "protocol": 22, + "endpoint_generation": 1, + "tag": "preview-2026-09-29-8e78f929d8f0", + "assets": { + "linux-x86_64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-linux-x86_64", + "sha256": "6f3dffff0c9805e414ff9285c0a5ce8ff8bd1c0118383360048837baad8ad6f5" + }, + "linux-aarch64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-linux-aarch64", + "sha256": "f26292297337d1b54dc9d1f01e473d4c95d572410577aac70534a69bb9123b91" + }, + "macos-x86_64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-macos-x86_64", + "sha256": "7cdf43b44cb4c0731a98932aeabe992e75781f4eead337bc52aa6889eff188ff" + }, + "macos-aarch64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-macos-aarch64", + "sha256": "7ebb310f974eaac7e45e9a46db470de11b24050dd929314757c952459bceaf3f" + }, + "windows-x86_64": { + "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-09-29-8e78f929d8f0/herdr-windows-x86_64.zip", + "sha256": "bbebbd192fc6356228efdfb89ad1ce86813f3aff41ad48dbf5082fbe94e2485c", + "format": "zip" + } + } + }, "2026-09-29-9dc3a1df2b56": { "base_version": "0.9.1", "commit": "9dc3a1df2b563df0637264fc0dffcd607c324ac5", @@ -886,31 +917,6 @@ "sha256": "4bd46e2f4e3d76bf730b105fe11de53093c5b580b7e0a042359a887c5ac6aef0" } } - }, - "2026-06-04-670656b26f1a": { - "base_version": "0.6.8", - "commit": "670656b26f1aeadc3f18e6692a9fdf1b02da799c", - "built_at": "2026-06-04T19:48:01Z", - "protocol": 12, - "tag": "preview-2026-06-04-670656b26f1a", - "assets": { - "linux-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-04-670656b26f1a/herdr-linux-x86_64", - "sha256": "24dbbcc8f56d0d6fb05f08b30b42034de10155f09326a9f535810d0f4d53812a" - }, - "linux-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-04-670656b26f1a/herdr-linux-aarch64", - "sha256": "8f3708274a4e56f613709d05b4b8d56ba8d7b3a10705c12f2b57899cc5ff105b" - }, - "macos-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-04-670656b26f1a/herdr-macos-x86_64", - "sha256": "1a24cc6793a61a70c5e9a52514b809d267adde795152dd236f854048a82aa4bf" - }, - "macos-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/preview-2026-06-04-670656b26f1a/herdr-macos-aarch64", - "sha256": "396c97c613f33e490f66c36456d47cfb34dd9aca50a5911ef0adf6e1914c6c4c" - } - } } } } diff --git a/docs/preview/website/src/content/docs/add-herdr-support.mdx b/docs/preview/website/src/content/docs/add-herdr-support.mdx index 0ed689a3..b3e46286 100644 --- a/docs/preview/website/src/content/docs/add-herdr-support.mdx +++ b/docs/preview/website/src/content/docs/add-herdr-support.mdx @@ -67,10 +67,11 @@ You can attach the command to any state report, or send it with `pane report-age After a Herdr server restart, Herdr opens the pane in the same directory and runs that command there. The command must follow these rules: - The first word is a plain command name on the user's `PATH`, such as `my-agent`, not a path. -- No argument contains an apostrophe. +- No argument contains an apostrophe or a control character. +- At most 64 arguments and 8 KiB in total. - Your source must hold the pane first, so send a state report with `report-agent` before or along with the command. Otherwise Herdr answers with `resume_not_accepted`. -Herdr rejects a command that breaks the first two rules with `invalid_resume_argv` and does not apply that report. Users can turn off resume with `[session] resume_agents_on_restore = false`. +Herdr rejects a command that breaks the first three rules with `invalid_resume_argv` and does not apply that report. Users can turn off resume with `[session] resume_agents_on_restore = false`. ## Release on exit @@ -89,7 +90,7 @@ If your agent exits without releasing, Herdr notices once the pane is back at it - Don't let Herdr slow your agent down. Send reports in the background or with a short timeout, and ignore failures. - Send only the latest state. If several changes queue up while a report is in flight, drop the older ones. -- Older Herdr versions ignore the resume command, so everything else keeps working there. +- Resume commands need Herdr 0.10.0 or later. Older versions ignore them, so state reports and release keep working there. ## Use the socket directly diff --git a/docs/preview/website/src/content/docs/agents.mdx b/docs/preview/website/src/content/docs/agents.mdx index 5c4351a5..f843196a 100644 --- a/docs/preview/website/src/content/docs/agents.mdx +++ b/docs/preview/website/src/content/docs/agents.mdx @@ -1,6 +1,6 @@ --- title: Agents -description: See what Herdr can detect, how agent state works, and how integrations improve it. +description: See which coding agents work with Herdr, either supported by Herdr or supporting Herdr themselves, and how agent state works. --- Herdr is built for running more than one coding agent at a time. Each agent stays in a real terminal pane with its shell, logs, prompts, and running processes intact. Herdr tracks which panes contain agents, rolls their state up to tabs and workspaces, and lets you jump straight to the pane that needs attention instead of polling every terminal by hand. @@ -9,46 +9,58 @@ To coordinate agents from scripts or from another agent, see [Agent automation]( ## Supported agents -Automatic detection works out of the box for common coding agents. The table shows which signal determines `idle`, `working`, and `blocked` for each one. +Agents get Herdr support in one of two ways: Herdr supports them, or they support Herdr themselves. Either way you see each agent's `idle`, `working`, and `blocked` state, get notified when it finishes or needs you, and can wait on it from scripts. -| Agent | State authority | Integration role | +Other agents still run normally in Herdr panes. They just show up as plain terminals. + +### Supported by Herdr + +Herdr recognizes these agents and reads their state from what they draw on screen. To get the same session back after a Herdr server restart, install the agent's integration with `herdr integration install `. See [Integrations](/docs/integrations/) for what each one installs. + +| Agent | Integration | Notes | | --- | --- | --- | -| Pi | lifecycle hooks when installed; otherwise screen manifest | state and session | -| OMP | lifecycle hooks when installed | state and session | -| GitHub Copilot CLI | screen manifest | session | -| Devin CLI | screen manifest | session | -| Kimi Code CLI | lifecycle hooks when installed; otherwise screen manifest | state and session | -| Hermes Agent | screen manifest | session | -| Qoder CLI | screen manifest | session | -| Qwen Code | screen manifest | session | -| Letta Code | screen manifest | session | -| Droid | screen manifest | session | -| OpenCode | lifecycle plugin when installed; otherwise screen manifest | state and session | -| Kilo Code CLI | lifecycle plugin when installed; otherwise screen manifest | state and session | -| MastraCode | lifecycle hooks when installed | state and session | -| Claude Code | screen manifest | session | -| Codex | screen manifest | session | -| Cursor Agent CLI | screen manifest | session | -| Amp | screen manifest | none | -| Grok CLI | screen manifest | session | -| Antigravity CLI | screen manifest | session | -| Kiro CLI | screen manifest | none | -| Maki | screen manifest | none | -| Muse | screen manifest | none | +| Claude Code | `claude` | | +| Codex | `codex` | | +| GitHub Copilot CLI | `copilot` | | +| Cursor Agent CLI | `cursor` | | +| OpenCode | `opencode` | also reports state | +| Pi | `pi` | also reports state | +| OMP | `omp` | state requires the integration | +| Droid | `droid` | | +| Devin CLI | `devin` | | +| Kimi Code CLI | `kimi` | also reports state | +| Kilo Code CLI | `kilo` | also reports state | +| Hermes Agent | `hermes` | | +| Qoder CLI | `qodercli` | | +| Qwen Code | `qwen` | | +| Letta Code | `letta` | CLI install only | +| MastraCode | `mastracode` | state requires the integration | +| Grok CLI | `grok` | | +| Antigravity CLI | `antigravity-cli` | | +| Amp | none | state only | +| Kiro CLI | none | state only | +| Maki | none | state only | +| Gemini CLI | none | state only, less tested | +| Cline | none | state only, less tested | -Detected but less thoroughly tested: Gemini CLI and Cline. Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API. +### Supported by the agent -## Status authority +These agents report their own state to Herdr. There is nothing to install; run them in a Herdr pane. -Herdr first detects the foreground process in each pane. After that, each pane has one status authority. +- [Crush](https://github.com/charmbracelet/crush) +- Command Code +- Muse +- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) -For agents with complete lifecycle hooks, the integration is authoritative when it is installed and actively reporting for the running pane. Herdr uses those hook reports for `idle`, `working`, `blocked`, and session identity. It does not also run screen manifest fallback for that same lifecycle authority. This avoids two competing sources of truth. +An agent that also reports its resume command comes back in the same session after a Herdr server restart. -For agents without complete lifecycle hooks, Herdr identifies the foreground process and reads the live bottom-buffer screen snapshot. It evaluates TOML manifests against that snapshot to classify `idle`, `working`, and `blocked`. For agents that emit them, manifests can also match terminal title and progress (OSC) sequences as detection evidence; when that evidence is absent, screen rules carry detection on their own. +If you build a coding agent, [Add Herdr support to your agent](/docs/add-herdr-support/) shows how to join this list. It takes a few calls to Herdr's CLI or socket, and no change to Herdr. -The screen snapshot comes from the recent bottom of the pane buffer, not the scrolled viewport. If you scroll back in Herdr, detection still follows the live agent UI at the bottom. +## How status works -Integrations marked `session` in the table above are intentionally not lifecycle authorities. They provide native session identity for restore, but their hooks do not cover the whole lifecycle. They can miss permission approval results, escape interrupts, or other transitions. For those agents, Herdr still uses screen manifest detection. +For agents Herdr supports, Herdr finds the agent's process in each pane and reads the live bottom of the pane, not the part you scrolled to. Rules in a detection manifest decide whether that screen means `idle`, `working`, or `blocked`. When an integration also reports state, Herdr uses those reports instead of reading the screen. + +For agents that support Herdr, the agent's own reports decide the state. ## VMs and sandbox wrappers @@ -107,17 +119,6 @@ A blocked agent makes its pane, tab, and workspace look blocked. A working agent This is the main Herdr workflow: start several agents, let them work in parallel, and use the sidebar to see which project needs a decision, which one is still running, and which one is ready to review. -## Direct integrations - -Install the integration for each agent you use to give Herdr hook or plugin reports instead of screen detection alone: - -```bash -herdr integration install claude -herdr integration status -``` - -Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list. If you are building an agent, [Add Herdr support to your agent](/docs/add-herdr-support/) shows how to report lifecycle state and a resume command without adding native support to Herdr. - ## Custom agent labels You can rename an agent target for display: diff --git a/docs/preview/website/src/content/docs/configuration.mdx b/docs/preview/website/src/content/docs/configuration.mdx index 33644e1c..9188dbb5 100644 --- a/docs/preview/website/src/content/docs/configuration.mdx +++ b/docs/preview/website/src/content/docs/configuration.mdx @@ -525,7 +525,7 @@ Search the [Config reference](/docs/config-reference/) for scrollback limits, ne Applications and plugins integrate through the standard Kitty graphics protocol emitted in pane terminal output. Herdr renders these images by default in compatible outer terminals. The external socket pane-overlay API has been removed; there is no replacement socket image API. -Popups, menus, and notifications temporarily hide only the image placements they overlap. Uncovered images stay visible, and hidden placements return when uncovered. Images do not dim with dialog backgrounds. +Popups, menus, and notifications crop images around the area they cover; the rest of each image stays visible and the covered part returns when the overlay closes. Images do not dim with dialog backgrounds. Herdr automatically chooses eligible file transports, with no application changes or environment switches. On local Unix Ghostty clients, it can send image data through temporary files instead of encoding it into terminal output. A small file-consumption probe checks support first. Other terminals, SSH-launched clients, and nested multiplexers retain inline output for this last-hop optimization. diff --git a/docs/preview/website/src/content/docs/integrations.mdx b/docs/preview/website/src/content/docs/integrations.mdx index 3aff5ae1..691bc306 100644 --- a/docs/preview/website/src/content/docs/integrations.mdx +++ b/docs/preview/website/src/content/docs/integrations.mdx @@ -3,7 +3,7 @@ title: Integrations description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, MastraCode, Antigravity CLI, and Grok CLI. --- -Herdr detects supported agents automatically. Install official integrations when you want native agent session restore, direct lifecycle reports, or both. See [Agents](/docs/agents/) for the full status authority model. +Herdr detects the agents it supports automatically. Install an agent's integration so Herdr can resume the same session after a server restart. Some integrations also report the agent's state directly. See [Agents](/docs/agents/) for which agents Herdr supports and which support Herdr themselves. ## Install integrations @@ -57,16 +57,9 @@ Herdr saves integration configs atomically on Linux/macOS and for new files; exi ## How Herdr uses integrations -Herdr uses integrations in two ways: +Every integration tells Herdr which session the agent is in, so Herdr can resume it after a server restart. Turn this off with `[session] resume_agents_on_restore = false`. -| Integration type | Agents | Effect | -| --- | --- | --- | -| Lifecycle authority | Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, MastraCode | When installed and actively reporting for the pane, hook or plugin events author `idle`, `working`, and `blocked`. Herdr does not also use screen manifest fallback for that same lifecycle authority. | -| Session identity | Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, Hermes Agent, Antigravity CLI, Grok CLI | The integration reports native session references for restore. State still comes from Herdr's screen manifest detection. | - -Custom integrations can also report state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable. - -Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Qwen Code, Letta Code, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, MastraCode, and Antigravity CLI panes after a Herdr server restart unless `[session] resume_agents_on_restore = false` disables it. +The Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, and MastraCode integrations also report the agent's state. While they report, Herdr uses them instead of reading the screen. The others leave state to screen detection. Native session restore requires current Herdr integrations: Pi integration version `2`, OMP version `3`, Claude Code version `6`, Codex version `5`, GitHub Copilot CLI version `2`, Devin CLI version `2`, Droid version `2`, Kimi Code CLI version `3`, Qoder CLI version `2`, Qwen Code version `1`, Letta Code version `1`, Cursor Agent CLI version `1`, Grok CLI version `2`, OpenCode version `5`, Kilo Code CLI version `1`, Hermes Agent version `5`, MastraCode version `1`, or Antigravity CLI version `1`. Check installed versions with `herdr integration status`. diff --git a/docs/preview/website/src/content/docs/ja/add-herdr-support.mdx b/docs/preview/website/src/content/docs/ja/add-herdr-support.mdx index d095bc2d..234b4102 100644 --- a/docs/preview/website/src/content/docs/ja/add-herdr-support.mdx +++ b/docs/preview/website/src/content/docs/ja/add-herdr-support.mdx @@ -67,10 +67,11 @@ Herdr ペイン内のすべてのプロセスは、次の環境変数を継承 Herdr サーバーの再起動後、Herdr は同じディレクトリでペインを開き、そこでそのコマンドを実行します。コマンドは次のルールに従う必要があります: - 最初の語は、`my-agent` のようにユーザーの `PATH` 上にある単純なコマンド名にします。パスは使えません。 -- どの引数にもアポストロフィを含めません。 +- どの引数にもアポストロフィや制御文字を含めません。 +- 引数は最大 64 個、合計 8 KiB までです。 - 先に source がペインを保持している必要があります。コマンドより前か同時に、`report-agent` で状態を報告してください。そうしないと Herdr は `resume_not_accepted` を返します。 -最初の 2 つのルールに違反するコマンドは、Herdr が `invalid_resume_argv` で拒否し、その報告は適用されません。ユーザーは `[session] resume_agents_on_restore = false` で resume を無効にできます。 +最初の 3 つのルールに違反するコマンドは、Herdr が `invalid_resume_argv` で拒否し、その報告は適用されません。ユーザーは `[session] resume_agents_on_restore = false` で resume を無効にできます。 ## 終了時に解放する @@ -89,7 +90,7 @@ Herdr サーバーの再起動後、Herdr は同じディレクトリでペイ - Herdr のせいでエージェントを遅くしないでください。報告はバックグラウンドか短いタイムアウトで送り、失敗は無視します。 - 最新の状態だけを送ります。報告の送信中に複数の変化がたまったら、古いものは捨てます。 -- 古い Herdr は resume コマンドを無視するので、それ以外の機能はそのまま動きます。 +- resume コマンドには Herdr 0.10.0 以降が必要です。古いバージョンはこれを無視するので、状態の報告と解放はそのまま動きます。 ## ソケットを直接使う 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 f69d6a3a..0c6be486 100644 --- a/docs/preview/website/src/content/docs/ja/agent-automation.mdx +++ b/docs/preview/website/src/content/docs/ja/agent-automation.mdx @@ -77,6 +77,8 @@ herdr agent rename w1:p2 reviewer `idle` と `done` はどちらも入力可能な状態です。CLI/API はサーバーの既読状態を使い、未確認の idle を `done` とします。明示的な `pane focus` / `agent focus` は対象を既読にしますが、読み取りでは変わりません。各 TUI クライアントは表示済みの完了を独立して管理するため、Done バッジが CLI やほかのクライアントと異なる場合があります。`blocked` は承認または質問 UI を Herdr が認識した状態です。`unknown` はエージェントが存在するもののライフサイクルを確実に分類できない状態で、成功完了を意味しません。違いが重要なら正確な `--until` を指定してください。 +起動準備、idle な会話の復元、エージェント会話の切り替えは、作業の完了として数えません。起動直後に作業を始めるエージェントは、Herdr が先に idle プロンプトを確認しなくても最初のタスクを完了できます。エージェントのレスポンスには `completion_seq` が含まれる場合があり、誰が確認したかに関係なく、現在の idle 遷移が完了した作業であることを示します。これはその遷移の `state_change_seq` と一致し、起動やセッション変更では設定されません。古いサーバーではこのフィールドが省略される場合があります。古いサーバーに接続したクライアントは、観測した working 状態を使って Done バッジを保護するため、更新の合間に開始して終了したターンを見逃す可能性があります。 + タイムアウトや `agent_prompt_stalled` は、入力が送られていないことを保証しません。二重送信を避けるため、再試行の前にエージェントを読み取ってください。ID とエージェント名はサーバーごとに独立しています。TUI で別のマシンを選んでも、既存ペイン内の CLI コマンドの接続先は変わりません。 `pane wait-output` はエージェントのライフサイクルを解釈しません。選択したターミナルスナップショットをポーリングし、最初にすぐ検索するため、すでに存在する文字列も一致します。デフォルトのソース名は `recent` で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。`--lines` でその行数を変更でき、`--regex` は Rust の正規表現構文で 1 行ずつ一致します。 diff --git a/docs/preview/website/src/content/docs/ja/agents.mdx b/docs/preview/website/src/content/docs/ja/agents.mdx index cb71a678..f3bfaa96 100644 --- a/docs/preview/website/src/content/docs/ja/agents.mdx +++ b/docs/preview/website/src/content/docs/ja/agents.mdx @@ -1,6 +1,6 @@ --- title: エージェント -description: Herdr が何を検出できるか、エージェント状態の仕組み、インテグレーションによる精度向上。 +description: Herdr で使えるコーディングエージェント (Herdr が対応するもの、自ら Herdr に対応するもの) と、エージェント状態の仕組み。 --- Herdr は複数のコーディングエージェントを同時に動かすために作られています。各エージェントは、シェル、ログ、プロンプト、実行中プロセスをそのまま保った実際のターミナルペインの中にいます。Herdr はどのペインにエージェントがいるかを追跡し、その状態をタブとワークスペースに集約し、すべてのターミナルを手作業で見回る代わりに、注意が必要なペインへ直接ジャンプできるようにします。 @@ -9,46 +9,58 @@ Herdr は複数のコーディングエージェントを同時に動かすた ## 対応エージェント -一般的なコーディングエージェントは、追加設定なしで自動検出されます。重要な違いは Herdr がエージェントを見えるかどうかではありません。どのシグナルが `idle`、`working`、`blocked` を決定する権限を持つかです。 +エージェントが Herdr 対応になる方法は 2 つあります。Herdr がそのエージェントに対応するか、エージェント自身が Herdr に対応するかです。どちらでも、各エージェントの `idle`、`working`、`blocked` 状態が表示され、完了時や対応が必要なときに通知され、スクリプトから待機できます。 -| エージェント | 状態の権威 | インテグレーションの役割 | +それ以外のエージェントも Herdr のペインで普通に動きます。単に通常のターミナルとして表示されるだけです。 + +### Herdr が対応するエージェント + +Herdr はこれらのエージェントを認識し、画面の表示から状態を読み取ります。Herdr サーバーの再起動後に同じセッションへ戻るには、`herdr integration install ` でエージェントのインテグレーションをインストールしてください。各インテグレーションがインストールする内容は[インテグレーション](/ja/docs/integrations/)を参照してください。 + +| エージェント | インテグレーション | 備考 | | --- | --- | --- | -| Pi | インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト | 状態とセッション | -| OMP | インストール時はライフサイクルフック | 状態とセッション | -| GitHub Copilot CLI | スクリーンマニフェスト | セッション | -| Devin CLI | スクリーンマニフェスト | セッション | -| Kimi Code CLI | インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト | 状態とセッション | -| Hermes Agent | スクリーンマニフェスト | セッション | -| Qoder CLI | スクリーンマニフェスト | セッション | -| Qwen Code | スクリーンマニフェスト | セッション | -| Letta Code | スクリーンマニフェスト | セッション | -| Droid | スクリーンマニフェスト | セッション | -| OpenCode | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション | -| Kilo Code CLI | インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト | 状態とセッション | -| MastraCode | インストール時はライフサイクルフック | 状態とセッション | -| Claude Code | スクリーンマニフェスト | セッション | -| Codex | スクリーンマニフェスト | セッション | -| Cursor Agent CLI | スクリーンマニフェスト | セッション | -| Amp | スクリーンマニフェスト | なし | -| Grok CLI | スクリーンマニフェスト | セッション | -| Antigravity CLI | スクリーンマニフェスト | セッション | -| Kiro CLI | スクリーンマニフェスト | なし | -| Maki | スクリーンマニフェスト | なし | -| Muse | スクリーンマニフェスト | なし | +| Claude Code | `claude` | | +| Codex | `codex` | | +| GitHub Copilot CLI | `copilot` | | +| Cursor Agent CLI | `cursor` | | +| OpenCode | `opencode` | 状態も報告 | +| Pi | `pi` | 状態も報告 | +| OMP | `omp` | 状態にはインテグレーションが必要 | +| Droid | `droid` | | +| Devin CLI | `devin` | | +| Kimi Code CLI | `kimi` | 状態も報告 | +| Kilo Code CLI | `kilo` | 状態も報告 | +| Hermes Agent | `hermes` | | +| Qoder CLI | `qodercli` | | +| Qwen Code | `qwen` | | +| Letta Code | `letta` | CLI からのみインストール | +| MastraCode | `mastracode` | 状態にはインテグレーションが必要 | +| Grok CLI | `grok` | | +| Antigravity CLI | `antigravity-cli` | | +| Amp | なし | 状態のみ | +| Kiro CLI | なし | 状態のみ | +| Maki | なし | 状態のみ | +| Gemini CLI | なし | 状態のみ、テストは限定的 | +| Cline | なし | 状態のみ、テストは限定的 | -検出されるもののテストが薄いもの: Gemini CLI と Cline。未対応のエージェントも通常のターミナルプロセスとして問題なく動きます。ただし、インテグレーションを追加するかソケット API で状態を報告しない限り、詳細な状態は得られない可能性があります。 +### Herdr に対応するエージェント -## 状態の権威 +これらのエージェントは自分の状態を Herdr に報告します。インストールするものはありません。Herdr のペインで実行するだけです。 -Herdr はまず各ペインのフォアグラウンドプロセスを検出します。その後、各ペインはひとつの状態権威を持ちます。 +- [Crush](https://github.com/charmbracelet/crush) +- Command Code +- Muse +- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) -完全なライフサイクルフックを持つエージェントでは、インテグレーションがインストールされ、実行中のペインについて能動的に報告している間は、インテグレーションが権威です。Herdr はそのフック報告を `idle`、`working`、`blocked` とセッション識別に使います。同じライフサイクル権威に対してスクリーンマニフェストのフォールバックを並走させることはしません。これにより、真実の情報源が 2 つ競合する状況を避けます。 +resume コマンドも報告するエージェントは、Herdr サーバーの再起動後に同じセッションで戻ります。 -完全なライフサイクルフックを持たないエージェントでは、Herdr はフォアグラウンドプロセスを識別し、ライブの下部バッファのスクリーンスナップショットを読みます。そのスナップショットに対して TOML マニフェストを評価し、`idle`、`working`、`blocked` を分類します。それらを発するエージェントでは、マニフェストはターミナルタイトルと進捗 (OSC) シーケンスも検出の証拠としてマッチできます。その証拠がない場合は、スクリーンルールが単独で検出を担います。 +コーディングエージェントを開発している場合は、[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)でこの一覧に加わる方法を確認できます。Herdr の CLI かソケットを数回呼ぶだけで、Herdr 側の変更は不要です。 -スクリーンスナップショットは、スクロールされたビューポートではなく、ペインバッファの直近の下部から取得されます。Herdr でスクロールバックしても、検出は下部のライブなエージェント UI を追い続けます。 +## 状態の仕組み -上の表で「セッション」と記載されたインテグレーションは、意図的にライフサイクル権威にしていません。これらは復元のためのネイティブセッション識別を提供しますが、フックがライフサイクル全体をカバーしていません。許可承認の結果、Esc による中断、その他の遷移を見逃すことがあります。これらのエージェントでは、Herdr は引き続きスクリーンマニフェスト検出を使います。 +Herdr が対応するエージェントでは、Herdr は各ペインでエージェントのプロセスを見つけ、スクロールした位置ではなくペインのライブな下部を読みます。検出マニフェストのルールが、その画面が `idle`、`working`、`blocked` のどれかを判定します。インテグレーションが状態も報告している場合、Herdr は画面を読む代わりにその報告を使います。 + +Herdr に対応するエージェントでは、エージェント自身の報告が状態を決めます。 ## VM とサンドボックスラッパー @@ -58,9 +70,11 @@ Linux と macOS では、ホストから見えるラッパーが実際のエー ## blocked 状態 -スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。既知のエージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。 +スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が `blocked` と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。Codex 以外の既知エージェントでどのマニフェストルールにもマッチしない場合、Herdr は `idle` にフォールバックし、explain の出力ではそのフォールバックに `default_known_agent_idle_fallback` というラベルを付けます。Codex は、タイトルとコンポーザーがアクティブなターン中と応答後で同じに見える場合があるため、`unknown` にフォールバックします。 -つまり、見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、最初は `blocked` ではなく `idle` と表示されることがあります。こうしたやり取りによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。影響するのは表示上の状態と wait だけです。 +それら Codex 以外のエージェントでは、見慣れない新しいプロンプトが、Herdr がその画面の形を学習するまで、最初は `blocked` ではなく `idle` と表示されることがあります。誤分類の影響は表示上の状態と wait だけです。これによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。 + +Codex では、表示中のスピナーや稼働中のアクティビティタイマーから `working` を、表示中の承認プロンプトから `blocked` を判定できます。通常のタイトルやコンポーザー、スピナーがないことだけでは、ターンの終了を判定できません。そのため、Codex は応答後も `unknown` のままになることがあり、`idle` または完了を待つ処理はタイムアウトする場合があります。管理対象の起動では、初期コンポーザーをプロンプト受付可能になったかの判定にのみ使います。この観測によってターン状態は変わりません。 ## 検出マニフェスト @@ -105,17 +119,6 @@ blocked なエージェントは、そのペイン、タブ、ワークスペー これが Herdr の中心的なワークフローです: 複数のエージェントを起動し、並行して働かせ、サイドバーでどのプロジェクトが判断を必要としているか、どれがまだ実行中か、どれがレビュー待ちかを把握します。 -## ダイレクトインテグレーション - -使っている各エージェントのインテグレーションをインストールしてください。スクリーン検出だけに頼らず、フックやプラグインの報告を Herdr に提供します: - -```bash -herdr integration install claude -herdr integration status -``` - -対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧は[インテグレーション](/ja/docs/integrations/)を参照してください。エージェントを開発している場合は、[エージェントに Herdr 対応を追加する](/ja/docs/add-herdr-support/)で、Herdr にネイティブサポートを追加せずにライフサイクル状態と resume コマンドを報告する方法を確認できます。 - ## カスタムエージェントラベル 表示用にエージェントターゲットの名前を変えられます: 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 2904b069..446f1374 100644 --- a/docs/preview/website/src/content/docs/ja/cli-reference.mdx +++ b/docs/preview/website/src/content/docs/ja/cli-reference.mdx @@ -49,6 +49,7 @@ herdr api schema --output herdr-api.schema.json ```bash herdr machine list +herdr machine add workbox herdr machine add workbox --label "Build machine" herdr machine rename --label "New name" herdr machine disable @@ -56,7 +57,7 @@ herdr machine enable herdr machine remove ``` -`machine add` はリモートのデフォルトセッションを使います。名前付きセッションを使う場合だけ `--remote-session ` を追加します。スクリプトでは `machine list` に `--json` を追加できます。詳しくは[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。 +対話型ターミナルでは、`machine add` は実行中のセッションを検出し、複数あれば選択できます。実行中のセッションがない場合や Herdr がインストールされていない場合は `default` を使います。インストール済みバイナリへの問い合わせに失敗した場合は、明示的な選択が必要です。検出を省略するには `--remote-session ` を追加します。非対話型コマンドでは、このフラグがない限り `default` を使います。スクリプトでは `machine list` に `--json` を追加できます。詳しくは[マシンへの接続](/ja/docs/connecting-machines/)を参照してください。 `machine add` はリモート側の Herdr が必要な機能を備えているか確認し、必要な場合だけ承認を得てインストールまたは更新します。指定したセッションのバックグラウンドサーバーを起動してからプロファイルを保存します。互換性があればリリースバージョンは一致しなくてもかまいません。インストールや再起動の承認が必要な場合は、対話型ターミナルで実行してください。セットアップが失敗またはキャンセルされた場合、プロファイルは保存されません。実行中サーバーの置き換えには明示的な承認が必要で、デフォルトの回答は No です。停止するとペインのプロセスも終了します。`machine add` は実験的なハンドオフを暗黙に有効にしません。 @@ -473,6 +474,8 @@ herdr plugin pane close `plugin pane open` は、プラグインがリンクされ、有効で、現在のプラットフォームと互換であることを要求します。マニフェストで宣言された `[[panes]]` コマンドを Herdr 管理のターミナルペインとして起動します。マニフェストのデフォルトは `overlay` で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペイン、またはタブレイアウトを変更しないセッションモーダルな `popup` として開くこともできます。`--width` と `--height` は、外側のポップアップ寸法をターミナルセル数または `80%` のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値はポップアップの最小サイズに制限されます。ポップアップは Herdr ペインではなく、`HERDR_PANE_ID` を受け取らず、pane API やエージェント API に参加しません。ターミナル以外のネイティブなプラグインペインは今後の対応面です。 +新しいペインでは `TERM_PROGRAM=herdr` として識別され、`TERM_PROGRAM_VERSION` には Herdr のバージョンが設定されます。`TERM=xterm-256color` と `COLORTERM=truecolor` は維持されます。Herdr は、明示的な起動環境の値を適用する前に、継承した外側のターミナルのセッションマーカー（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen、Zellij）、iTerm2 の `LC_TERMINAL` 識別子、既知の Claude Code、Codex、OMP セッションマーカーを削除します。これにより、新しいペインがサーバーを最初に起動したターミナルやエージェントのセッションを名乗ることを防ぎます。API キーやディスプレイ設定を含む通常の環境変数は、アタッチ中クライアントの環境に置き換えられず、引き続き継承されます。SSH エージェント転送には独自の再接続処理があります。このクリーンアップによって既存ペインのプロセスは変更されません。 + `--env KEY=VALUE` はプロセスを起動するコマンドで繰り返し指定できます。新しく起動されるプロセスにのみ適用されます。`HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_ENTRYPOINT_ID`、`HERDR_PLUGIN_CONTEXT_JSON` のような Herdr 管理の変数は、呼び出し側が与えた環境変数と衝突した場合も権威を保ちます。 ## 読み取りソース diff --git a/docs/preview/website/src/content/docs/ja/configuration.mdx b/docs/preview/website/src/content/docs/ja/configuration.mdx index 65b683f8..0759b432 100644 --- a/docs/preview/website/src/content/docs/ja/configuration.mdx +++ b/docs/preview/website/src/content/docs/ja/configuration.mdx @@ -73,7 +73,7 @@ headless_rows = 50 default_shell = "nu" ``` -未設定または空の場合、Herdr は `$SHELL`、次に Unix では `/bin/sh`、Windows では PowerShell を使います。これは実行ファイル名またはパスであり、シェルのコマンドラインではありません。既存のペインは再作成されるまで現在のシェルを保ちます。カスタムコマンドキーバインドの文字列は、Unix ではペインコマンドに `/bin/sh -c`、デタッチコマンドに `/bin/sh -lc` を通して実行され、Windows では `cmd.exe /d /c` を通して実行されます。 +未設定または空の場合、Herdr は Unix では `$SHELL`、次に `/bin/sh` を使います。Windows では、`PATH` 上で解決できる場合は `pwsh.exe`（PowerShell 7）を使い、それ以外は標準搭載の `powershell.exe`（Windows PowerShell 5.1）を使います。これは実行ファイル名またはパスであり、シェルのコマンドラインではありません。既存のペインは再作成されるまで現在のシェルを保ちます。カスタムコマンドキーバインドの文字列は、Unix ではペインコマンドに `/bin/sh -c`、デタッチコマンドに `/bin/sh -lc` を通して実行され、Windows では `cmd.exe /d /c` を通して実行されます。 新しく作成される対話型ペインのシェルの起動方法を設定します: @@ -142,6 +142,15 @@ navigate_pane_down = "ctrl+j" split_horizontal = "prefix+minus" ``` +`keys.prefix` は、複数のキーからプレフィックスモードに入りたい場合には配列も受け付けます。たとえば、macOS とリモート Linux マシンで 1 つの設定を共有できます: + +```toml +[keys] +prefix = ["ctrl+space", "ctrl+s"] +``` + +設定したどのプレフィックスでも同じプレフィックスモードに入り、すべての `prefix+...` アクションを開始できます。最初の項目がステータスバーに表示されるプライマリプレフィックスとなり、`prefix+?` のアプリ内ヘルプパネルにはすべてのプレフィックスが表示されます。 + デフォルトのキーマップはプレフィックス優先なので、Herdr がシェル、エディタ、tmux、ターミナルアプリから入力を奪うことはありません。[設定リファレンス](/docs/config-reference/)で `keys.` を検索すると、すべてのアクションとデフォルトのバインドを確認できます。`prefix+?` で開くアプリ内ヘルプパネルには、現在有効なバインドが表示されます。 1 つのアクションに複数のショートカットが必要な場合、バインドを配列にすることもできます: @@ -244,6 +253,8 @@ name = "catppuccin" すべての組み込みテーマは、[設定リファレンス](/docs/config-reference/)で `theme.name` を検索してください。Herdr の UI 色をホストターミナルの ANSI パレットに従わせたいときは `terminal` を使ってください。 +Unix では、リサイズまたは `SIGWINCH` 後の再描画時にも、Herdr はホストターミナルの色を再読み込みします。テーマ切り替えツールがライト/ダーク通知を送らずに OSC でターミナル色を変更する場合は、新しいパレットを適用した後に `kill -WINCH ` を送ってください。サーバーではなく、アタッチ中の Herdr クライアントを対象にします。既存のペインは動作し続けます。直接の `herdr terminal attach` セッションでは、パレットの問い合わせはアタッチ先アプリケーションに委ねられます。 + ホストターミナルがライト/ダークの外観変更を報告したときに、Herdr が自身の UI テーマを切り替えるようにするには、テーマの自動切り替えを有効にします: ```toml @@ -508,9 +519,19 @@ claude = "on" ## Kitty graphics -Herdr は、対応する外側のターミナルでペイン画像をデフォルトで描画します。ポップアップ、メニュー、通知は、重なる画像の配置だけを一時的に隠します。重ならない画像は表示されたままで、隠れた配置は覆いがなくなると戻ります。画像はダイアログの背景と一緒に暗くなりません。 +アプリケーションとプラグインは、ペインのターミナル出力に送られる標準の Kitty graphics プロトコルを通じて統合します。Herdr は、対応する外側のターミナルでこれらの画像をデフォルトで描画します。外部ソケットのペインオーバーレイ API は削除され、代替となるソケット画像 API はありません。 -グラフィックス描画とペイングラフィックス API を無効にするには、次のように設定します: +ポップアップ、メニュー、通知は、覆う領域に合わせて画像を切り抜きます。各画像の残りは表示されたままで、覆われた部分はオーバーレイが閉じると戻ります。画像はダイアログの背景と一緒に暗くなりません。 + +Herdr は、アプリケーションの変更や環境変数による切り替えなしで、利用可能なファイル転送方式を自動的に選びます。ローカル Unix の Ghostty クライアントでは、画像データをターミナル出力へエンコードする代わりに、一時ファイル経由で送信できます。最初に小さなファイル読み取りプローブで対応状況を確認します。その他のターミナル、SSH で起動したクライアント、ネストしたマルチプレクサーでは、この最終区間の最適化にインライン出力を使い続けます。 + +対象となるローカルクライアントでは、ネイティブ RGBA 画像はピクセルバイトではなく、Herdr が所有するスナップショットへのパスとしてサーバーからクライアントへ送られます。未対応のクライアントや失敗した転送はインライン配信にフォールバックします。リモートサーバーのパスがローカルターミナルへ転送されることはありません。画像の配置、クリッピング、可視性は Herdr が管理します。 + +Linux では、ファイル全体を使う非圧縮 RGBA アップロードについて、Herdr がピクセルを読み取る前にコピーオンライトのスナップショットを作成できます。これには、Herdr 専用の `/var/tmp` ストアへのクローンをファイルシステムがサポートしている必要があります。未対応のファイルシステム、一時ファイルのアップロード、共有メモリ、その他の形式では通常のローダーを使います。スナップショットは 1 個あたり 16 MiB、合計 64 MiB に制限されます。アニメーションと未対応クライアントでは、必要な時点でピクセルを読み取ります。Herdr は画像を受理した後、変更可能な生成元パスに依存しません。 + +PNG アップロードでは完全なデコードと検証を引き続き行います。破損画像の検証を外側のターミナルへ先送りすることはありません。 + +Kitty graphics の描画を無効にするには、次のように設定します: ```toml [terminal] @@ -519,7 +540,7 @@ kitty_graphics = false 既存の設定との互換性のため、従来の `experimental.kitty_graphics` 設定も引き続き使用できます。両方が設定されている場合は、`terminal.kitty_graphics` が優先されます。 -この設定を変更した場合は、対象の Herdr サーバーを再起動するか、クライアントを再アタッチする必要があります。リモートセッションでは、サーバー側の設定がペイングラフィックスの解析と API の可用性を制御し、ローカルクライアント側の設定が外側のターミナルへの出力を制御します。 +この設定を変更した場合は、対象の Herdr サーバーを再起動するか、クライアントを再アタッチする必要があります。リモートセッションでは、サーバー側の設定が Kitty graphics の解析を制御し、ローカルクライアント側の設定が外側のターミナルへの出力を制御します。 ## Agent セッション復元 diff --git a/docs/preview/website/src/content/docs/ja/connecting-machines.mdx b/docs/preview/website/src/content/docs/ja/connecting-machines.mdx index ef8bb5bc..9a9e0dc7 100644 --- a/docs/preview/website/src/content/docs/ja/connecting-machines.mdx +++ b/docs/preview/website/src/content/docs/ja/connecting-machines.mdx @@ -7,6 +7,8 @@ description: Local と保存済み SSH マシンを 1 つの Herdr ウィンド 各マシンは独自の Herdr サーバー、セッション、プロセスを保持します。1 台への接続が切れても、ほかの接続は切れません。 +Herdr は、帯域が限られた接続で画面更新の通信量を減らすため、SSH 圧縮を要求します。互換性のある古い Herdr サーバーでも動作し、キー入力などの入力の届け方は変わりません。Herdr の `-C` オプションは SSH 設定の `Compression no` を上書きします。SSH が外部の ControlMaster を通じて既存接続を再利用する場合、その接続では元の圧縮設定が維持されます。 + ### SSH 認証の復旧 Linux と macOS で `remote.manage_ssh_config=true` の場合、マシン追加、サイドバー、API 操作は承認済み OpenSSH 接続を共有します。`herdr machine status [] [--json]` は認証を求めず、現在の接続状態を確認します。**reachable** はリモート Herdr が利用可能という意味で、各 TUI の接続状態ではありません。ターミナルで `herdr machine reconnect ` を実行すると、SSH 認証後に保存済みマシンを検証します。インストールや更新は行いません。開いているクライアントは 30 秒以内に再試行し、再起動は不要です。**`! auth`**、**`! error`**、失敗後の再接続ステータスをクリックすると、最新のエラーと CLI コマンドが通知に表示されます。認証ポップアップは開きません。マシン行の展開・折りたたみは変更されません。 @@ -30,17 +32,23 @@ ssh workbox インストールや置き換えの前に確認できるよう、対話型ターミナルで実行します: ```bash -herdr machine add workbox --label "Build machine" +herdr machine add workbox ``` -リモートのデフォルトセッションを使います。1 つのプロファイルは 1 つのリモートセッションを対象とし、そのホストの全セッションをまとめるものではありません。 +対話型ターミナルでは、Herdr は実行中のセッションを検出します。1 つだけならそれを選択し、複数ある場合は Up/Down と Enter で選べます。Esc または Ctrl+C でキャンセルします。問い合わせに成功しても実行中のセッションがなければ、セットアップは `default` を使います。Herdr がインストールされていない場合は、`default` 用にインストールするか確認します。インストール済みバイナリがセッションを報告できない場合はエラーを表示します。セッションを明示的に選ぶには `--remote-session ` を指定してください。 -名前付きセッションを使いたい場合だけ、任意の `--remote-session` を追加します: +デフォルトセッションはサイドバーに `workbox` と表示されます。これは `user@` プレフィックスを除いた SSH ホストです。別の名前にするには `--label "Build machine"` を追加します。1 つのプロファイルは 1 つのリモートセッションを対象とし、そのホストの全セッションをまとめるものではありません。非対話型コマンドでは、`--remote-session` がない限り `default` を使います。 + +検出を省略して特定のセッションを使うには、`--remote-session` を追加します: ```bash -herdr machine add workbox --label "Build machine" --remote-session agents +herdr machine add workbox --remote-session agents ``` +`--label` がない場合、このマシンは `workbox/agents` と表示されます。デフォルト名がすでに使われている場合、`machine add` は `--label` の指定を求めます。 + +Windows サーバーでは、SSH ユーザーが所有する Herdr プロセスで使われている実行ファイルも確認します。再利用前に機能を検証するため、SSH の `PATH` が古いインストールを指していても、互換性のある実行中ビルドを利用できます。 + Herdr はインストール済みバイナリと実行中サーバーをそれぞれ確認し、対象のバックグラウンドサーバーを起動してからプロファイルを保存します。互換性があればクライアントとサーバーのバージョンは一致しなくても構いません。未インストールや非互換の場合は、承認付きのセットアップを行います。実行中サーバーの置き換えが必要なら、サーバーとペインのプロセスを停止する前に確認し、その後に互換サーバーを起動します。デフォルトの回答は No です。インストールと置き換えの両方が必要な場合は、1 回の確認で承認します。`machine add` は実験的なライブハンドオフを使いません。セットアップをキャンセルした場合や失敗した場合、プロファイルは保存されません。 `herdr` で UI を開きます。ローカルクライアントがすでに開いていれば、追加や有効化したマシンは通常 1 秒以内に表示され、選択を変えずにバックグラウンドで接続します。マシン切り替え中の変更は、切り替えの完了後に反映します。セットアップ終了後もリモートサーバーは動き続けます。 @@ -95,6 +103,10 @@ herdr --remote workbox 認証に失敗したら、まず通常の SSH を確認します。パスフレーズ付きの鍵は、非対話型のバックグラウンド接続を始める前に `ssh-add` で読み込んでください。 +リモートペイン内で Git 認証や SSH 署名を使うには、信頼できるホストについて SSH 設定で `ForwardAgent yes` を有効にしてください。Herdr が転送を有効にすることはありません。セッションがエージェント付きで起動した場合、更新済みの Linux と macOS サーバーはペインに安定したエージェントアドレスを与えるため、`--remote` または保存済みマシンが再接続した後も、既存ペインと新規ペインの両方で転送されたエージェントを利用できます。動作中の継承エージェントや先行接続は、後から接続したクライアントや一時的なセットアップ確認より優先されます。それが消えた場合は、別の稼働中アタッチがエージェントを提供できます。 + +これにはローカルクライアントだけでなく、更新済みのリモートサーバーが必要です。エージェントなしで開始したローカルセッションでは `SSH_AUTH_SOCK` を変更しません。サーバー更新前、またはセッションに初めてエージェントが提供される前に作成されたペインは元の環境を維持するため、安定したアドレスを継承するには一度作り直す必要があります。互換性のある古いサーバーやエージェント転送なしの接続も、通常どおりアタッチできます。 + ## 設定と自動化 UI はデフォルトでクライアントのローカルテーマ、サイドバー設定、キーバインドを使います。選択中サーバーが公開するカスタムコマンドとプラグインは、そのサーバーで実行します。Herdr はローカルのプラグイン、設定、実行ファイル、シークレットを SSH ホストにコピーしません。リモートにコマンドがなければエラーを表示します。クライアント設定を編集したら UI の `reload config` を使います。[設定](/ja/docs/configuration/)を参照してください。 @@ -107,6 +119,8 @@ UI はデフォルトでクライアントのローカルテーマ、サイド 保存するのは、不透明な ID、ラベル、SSH 接続先、明示的なリモートセッション名、有効状態だけです。パスワード、秘密鍵、エージェントのチケット、SSH 制御ソケットはカタログに保存しません。認証は OpenSSH が扱います。 +Herdr は、`--machine` コマンドを繰り返し実行するときに検出を省略できるよう、各マシンのリモート OS と解決済み実行ファイルパスを別途記憶します。既存のプロファイルでは、初回使用時に不足情報を学習します。このキャッシュは任意です。キャッシュファイルがない、不正、または書き込み不能でもコマンドの動作は妨げられません。コマンドは引き続き実行中サーバーの互換性を確認します。キャッシュした実行ファイルがない、または API 転送に対応しなくなった場合、最初の読み取り専用確認中に再検出します。リモートの状態をすでに変更した可能性があるコマンドを自動的に再実行することはありません。 + クライアントとサーバーは同一バージョンを要求せず、互換性を合意します。保存済みマシンへの接続には、サーバーの `surface_interest` と `health_check` 能力も必要です。未対応の古いサーバーは、単独接続できても明示的に更新するまで Attention になります。そのほかの未対応メソッドは、該当する操作だけを無効にします。 互換クライアントを更新しても、リモートサーバーを置き換えたりエージェントを停止したりしません。新しいサーバー機能が必要なら、そのサーバーを明示的に更新します。通常の置き換えでは、サーバーとペインのプロセスを停止する前に確認します。 diff --git a/docs/preview/website/src/content/docs/ja/install.mdx b/docs/preview/website/src/content/docs/ja/install.mdx index 587f6df1..c23e9fb5 100644 --- a/docs/preview/website/src/content/docs/ja/install.mdx +++ b/docs/preview/website/src/content/docs/ja/install.mdx @@ -149,6 +149,8 @@ Windows の通常利用には安定版を推奨します。プレビューでは herdr update --handoff ``` +両方のサーバーがエージェント状態の転送に対応している場合、ライブハンドオフはフックが報告したエージェント状態を次の報告が届くまで維持します。古いサーバーからハンドオフすると、実行中のエージェントが一時的に idle と表示される場合があります。 + ライブハンドオフは Homebrew、mise、Nix のパッケージマネージャー経由のアップデートには適用されません。それらのインストールではパッケージマネージャーで更新し、再度 Herdr を実行して更新済みクライアントで再接続します。互換性のある古いサーバーは動き続けます。新しいリリースのサーバー側変更が必要になったときだけ、`herdr server stop` または `herdr session stop ` で後から再起動してください。 ## 動作要件 diff --git a/docs/preview/website/src/content/docs/ja/integrations.mdx b/docs/preview/website/src/content/docs/ja/integrations.mdx index 126ba824..d39d4056 100644 --- a/docs/preview/website/src/content/docs/ja/integrations.mdx +++ b/docs/preview/website/src/content/docs/ja/integrations.mdx @@ -3,7 +3,7 @@ title: インテグレーション description: Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、MastraCode、Antigravity CLI、Grok CLI 向けの Herdr インテグレーションをインストールします。 --- -Herdr は対応エージェントを自動的に検出します。公式インテグレーションは、復元のためのネイティブセッション識別、ライフサイクル状態の報告、またはその両方を追加できます。 +Herdr は対応するエージェントを自動的に検出します。エージェントのインテグレーションをインストールすると、サーバーの再起動後に Herdr が同じセッションを resume できます。一部のインテグレーションはエージェントの状態も直接報告します。Herdr が対応するエージェントと、自ら Herdr に対応するエージェントについては[エージェント](/ja/docs/agents/)を参照してください。 エージェントネイティブのセッション復元、直接のライフサイクル報告、またはその両方が欲しいときにインテグレーションを使ってください。状態権威モデルの全体像は[エージェント](/ja/docs/agents/)を参照してください。 @@ -59,16 +59,9 @@ Herdr は Linux/macOS の統合設定と全プラットフォームの新規フ ## Herdr がインテグレーションをどう使うか -Herdr はインテグレーションを 2 つの異なる方法で使います: +どのインテグレーションも、エージェントが今どのセッションにいるかを Herdr に伝えるので、サーバーの再起動後に Herdr がそのセッションを resume できます。`[session] resume_agents_on_restore = false` で無効にできます。 -| インテグレーションの種類 | エージェント | 効果 | -| --- | --- | --- | -| ライフサイクル権威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode | インストールされ、そのペインについて能動的に報告している間は、フックまたはプラグインのイベントが `idle`、`working`、`blocked` を決定します。同じライフサイクル権威に対して、Herdr はスクリーンマニフェストのフォールバックを併用しません。 | -| セッション識別 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、Hermes Agent、Antigravity CLI、Grok CLI | インテグレーションは復元用のネイティブセッション参照を報告します。状態は引き続き Herdr のスクリーンマニフェスト検出から得られます。 | - -カスタムインテグレーションも、ネイティブのターミナル UI では見えない状態を定義する場合に状態を報告できます。Herdr への組み込みや、認識済みのエージェント実行ファイルは必要ありません。 - -一部のインテグレーションは、エージェントのネイティブセッション参照を報告します。Herdr は公式のセッション参照を使って、`[session] resume_agents_on_restore = false` で無効化されていない限り、Herdr サーバーの再起動後に Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode、Antigravity CLI のペインを resume します。 +Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode のインテグレーションは、エージェントの状態も報告します。報告している間、Herdr は画面を読む代わりにその報告を使います。その他のインテグレーションでは、状態は画面検出に任せます。 エージェントネイティブのセッション復元には最新の Herdr インテグレーションが必要です: Pi インテグレーションはバージョン `2`、OMP は `3`、Claude Code は `6`、Codex は `5`、GitHub Copilot CLI は `2`、Devin CLI は `2`、Droid は `2`、Kimi Code CLI は `3`、Qoder CLI は `2`、Qwen Code は `1`、Letta Code は `1`、Cursor Agent CLI は `1`、Grok CLI は `2`、OpenCode は `5`、Kilo Code CLI は `1`、Hermes Agent は `5`、MastraCode は `1`、Antigravity CLI は `1` です。インストール済みバージョンは `herdr integration status` で確認してください。 @@ -202,7 +195,7 @@ herdr integration install opencode この連携は OpenCode V1 `1.18.29` 以降と OpenCode V2（beta `19242` で検証済み）に対応します。OpenCode の設定ディレクトリはあらかじめ存在している必要があります。Herdr はサーバー側のエントリポイントを `~/.config/opencode/plugins/herdr-agent-state.js` に、共通 TUI プラグインを同じ設定ディレクトリの `herdr-tui-session.js` に、V2 TUI エントリポイントを `herdr-opencode/tui.js` にインストールします。 -インストール時、V1 TUI プラグインを `tui.jsonc` に、V2 TUI プラグインを `cli.json` に登録し、他の設定やプラグインは保持します。OpenCode に移行すべき V1 TUI 設定(`tui.json` または `kv.json`)が残っている場合、Herdr は初回起動時の移行を妨げないよう登録を見送ります。その場合は一度 `opencode2` を起動してから連携を再インストールしてください。それ以外の場合は Herdr が `cli.json` を作成してプラグインを登録します。インストール後は OpenCode TUI を再起動してください。アンインストールは管理対象のプラグインファイルと設定項目を削除します。 +インストール時、V1 TUI プラグインを `tui.jsonc` に、V2 TUI プラグインを `cli.json` に登録し、他の設定やプラグインは保持します。`tui.json` に既存の V1 登録がある場合もインストール済みとみなし、`tui.jsonc` を作成せずに再利用します。アンインストールでは、両方の TUI 設定ファイルから Herdr の登録を削除し、ファイルと他の設定は保持します。OpenCode に移行すべき V1 TUI 設定（`tui.json` または `kv.json`）が残っている場合、Herdr は初回起動時の移行を妨げないよう登録を見送ります。その場合は一度 `opencode2` を起動してから連携を再インストールしてください。それ以外の場合は Herdr が `cli.json` を作成してプラグインを登録します。インストール後は OpenCode TUI を再起動してください。アンインストールは管理対象のプラグインファイルと設定項目を削除します。 V2 のライフサイクル報告はペイン内の TUI で実行され、複数のペインが同じ OpenCode サーバーを共有する場合も、選択されたルートセッションにイベントを対応付けます。完了時または中断時に working 状態を解除し、未処理の権限要求やフォーム、実行失敗は blocked 状態を維持します。V2 Mini とヘッドレスクライアントは TUI プラグインを実行しないため、このライフサイクル報告は利用できません。 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 361f5222..a03c52ce 100644 --- a/docs/preview/website/src/content/docs/ja/socket-api.mdx +++ b/docs/preview/website/src/content/docs/ja/socket-api.mdx @@ -486,6 +486,8 @@ Herdr はローカルソケット上の改行区切り JSON を使います。Un {"id":"req_1","result":{"type":"pong"}} ``` +JSON のデコードまで到達したリクエスト行では、メソッドやパラメーターが無効な場合も含め、エラーレスポンスにもリクエストの `id` がそのまま含まれます。JSON が無効、またはトップレベルの文字列 `id` を一意に特定できない場合、エラーレスポンスは空の `id` を使います。無効な UTF-8 などのトランスポートエラーでは、レスポンスを返さずに接続を閉じる場合があります。 + イベント購読は、最初のレスポンスの後も接続を開いたままにします。 ## ソケットパス @@ -545,7 +547,7 @@ Herdr はローカルソケット上の改行区切り JSON を使います。Un } ``` -どちらのメソッドも、Herdr サーバーの再起動後に報告元の現在のセッションを再開するコマンドを、省略可能な `resume_argv` 配列で受け付けます。最初の要素はパスではなく単純なコマンド名でなければならず、どの要素にもアポストロフィを含めることはできません。無効な値は `invalid_resume_argv` で失敗し、その報告は適用されません。カスタムエージェントは、コマンドを付ける前に `pane.report_agent` でペインを保持している必要があり、そうでない場合は `resume_not_accepted` で失敗します。Herdr は同じ `source` と `agent` がペインを保持している間だけコマンドを保持し、そのエージェントに対する Herdr 組み込みの resume コマンドより優先します。古い Herdr はこのフィールドを無視します。 +どちらのメソッドも、Herdr サーバーの再起動後に報告元の現在のセッションを再開するコマンドを、省略可能な `resume_argv` 配列で受け付けます。配列は最大 64 要素、合計 8 KiB までです。最初の要素はパスではなく単純なコマンド名でなければならず、どの要素にもアポストロフィや制御文字を含めることはできません。無効な値は `invalid_resume_argv` で失敗し、その報告は適用されません。カスタムエージェントは、コマンドを付ける前に `pane.report_agent` でペインを保持している必要があり、そうでない場合は `resume_not_accepted` で失敗します。Herdr は同じ `source` と `agent` がペインを保持している間だけコマンドを保持し、そのエージェントに対する Herdr 組み込みの resume コマンドより優先します。古い Herdr はこのフィールドを無視します。 ```json { @@ -642,7 +644,9 @@ workspace の get/list 応答は結果の `tokens` マップを公開し、ス } ``` -最初のレスポンスは購読の確認応答です。以降の行はプッシュされるイベントです。ライフサイクルイベントの購読はリクエストが受理された時点から始まり、それ以前に保持されていたイベントは再生しません。 +最初のレスポンスは購読の確認応答です。以降の行はプッシュされるイベントです。 +すべての項目が有効でなければなりません。参照先ペインが 1 つでも存在しない場合、Herdr はリクエスト全体をエラーで拒否し、接続を閉じます。他の項目が購読されたと仮定せず、ペイン一覧を更新して再試行してください。 +ライフサイクルイベントの購読はリクエストが受理された時点から始まり、それ以前に保持されていたイベントは再生しません。 ライフサイクルとエージェント状態のイベントは、各購読内の順序を保った上限付きのバッチで送信されます。イベント履歴は永続ログではありません。購読の初期化中も含め、購読者が保持範囲より遅れた場合、サーバーは元のリクエスト `id` と `error.code: "events_lost"` を含むエラーレスポンスを送り、その購読接続を閉じます。欠落したイベントを通知せずに配信を続けることはありません。他のクライアント接続には影響しません。履歴はイベント種別間で共有されるため、失われたイベントが購読条件に一致しなかった可能性があっても、保持範囲を超えたことを通知します。 diff --git a/docs/preview/website/src/content/docs/socket-api.mdx b/docs/preview/website/src/content/docs/socket-api.mdx index 9e844d7e..5becbd8e 100644 --- a/docs/preview/website/src/content/docs/socket-api.mdx +++ b/docs/preview/website/src/content/docs/socket-api.mdx @@ -687,7 +687,7 @@ Session-only official integrations report native session references with `pane.r } ``` -Both methods accept an optional `resume_argv` array with the command that resumes the reporter's current session after a Herdr server restart. Its first element must be a plain command name, not a path, and no element may contain an apostrophe; invalid values fail with `invalid_resume_argv` and the report is not applied. A custom agent must hold the pane through `pane.report_agent` before it can attach a command; otherwise the request fails with `resume_not_accepted`. Herdr keeps the command only while the same `source` and `agent` hold the pane, and it takes precedence over Herdr's built-in resume command for that agent. Older Herdr versions ignore the field. +Both methods accept an optional `resume_argv` array with the command that resumes the reporter's current session after a Herdr server restart. Its first element must be a plain command name, not a path. It allows at most 64 elements and 8 KiB in total, and no element may contain an apostrophe or control character; invalid values fail with `invalid_resume_argv` and the report is not applied. A custom agent must hold the pane through `pane.report_agent` before it can attach a command; otherwise the request fails with `resume_not_accepted`. Herdr keeps the command only while the same `source` and `agent` hold the pane, and it takes precedence over Herdr's built-in resume command for that agent. Older Herdr versions ignore the field. ```json { diff --git a/docs/preview/website/src/content/docs/zh-cn/add-herdr-support.mdx b/docs/preview/website/src/content/docs/zh-cn/add-herdr-support.mdx index 827fd233..bb7f1386 100644 --- a/docs/preview/website/src/content/docs/zh-cn/add-herdr-support.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/add-herdr-support.mdx @@ -67,10 +67,11 @@ Herdr 窗格中的每个进程都会继承这些环境变量: Herdr 服务器重启后,Herdr 会在同一目录中打开该窗格并在其中运行这条命令。命令必须遵守以下规则: - 第一个词是用户 `PATH` 上的普通命令名,例如 `my-agent`,不能是路径。 -- 任何参数都不能包含撇号。 +- 任何参数都不能包含撇号或控制字符。 +- 最多 64 个参数,总长度不超过 8 KiB。 - 你的来源必须先持有该窗格,所以请在发送命令之前或同时用 `report-agent` 上报状态。否则 Herdr 会返回 `resume_not_accepted`。 -违反前两条规则的命令会被 Herdr 以 `invalid_resume_argv` 拒绝,该次上报也不会生效。用户可以用 `[session] resume_agents_on_restore = false` 关闭恢复。 +违反前三条规则的命令会被 Herdr 以 `invalid_resume_argv` 拒绝,该次上报也不会生效。用户可以用 `[session] resume_agents_on_restore = false` 关闭恢复。 ## 退出时释放 @@ -89,7 +90,7 @@ Herdr 服务器重启后,Herdr 会在同一目录中打开该窗格并在其中 - 不要让 Herdr 拖慢你的智能体。在后台或用较短的超时发送上报,并忽略失败。 - 只发送最新状态。如果一次上报正在发送时积累了多个变化,丢弃较旧的那些。 -- 旧版 Herdr 会忽略恢复命令,其他功能照常工作。 +- 恢复命令需要 Herdr 0.10.0 或更高版本。旧版会忽略它,状态上报和释放照常工作。 ## 直接使用套接字 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 8ad27952..9476c65c 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 @@ -77,6 +77,8 @@ herdr agent rename w1:p2 reviewer `idle` 和 `done` 都表示可以接受输入。CLI/API 使用服务器的已查看状态：`done` 表示尚未标记为已查看的 idle；显式 `pane focus` / `agent focus` 会标记目标，读取不会。每个 TUI 客户端独立记录它已显示的完成状态，因此其 Done 标记可能与 CLI 或其他客户端不同。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示智能体存在,但 Herdr 无法可靠判断其生命周期;它不代表工作成功完成。区别重要时,请指定精确的 `--until` 状态。 +启动就绪、恢复空闲对话和切换智能体对话都不算工作完成。立即开始工作的智能体可以在 Herdr 首次看到空闲提示前完成第一个任务。智能体响应可能包含 `completion_seq`,它会独立于谁查看过响应,将当前 idle 转换标识为已完成的工作。该值与此次转换的 `state_change_seq` 相同;启动和会话切换不会设置它。旧服务器可能省略此字段。连接到旧服务器的客户端使用观察到的 working 状态来保护 Done 标记,因此可能漏掉在两次更新之间开始并完成的轮次。 + 超时或 `agent_prompt_stalled` 并不意味着没有发送输入。重试前请先读取智能体，避免重复提交同一提示。ID 和智能体名称只在所属服务器内有效；在 TUI 中切换机器不会改变已有窗格中 CLI 命令的目标。 `pane wait-output` 不解释智能体生命周期。它轮询选定的终端快照并立即进行第一次搜索,所以已经存在的文本也会匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制;`--regex` 使用 Rust 正则表达式语法并逐行匹配。 diff --git a/docs/preview/website/src/content/docs/zh-cn/agents.mdx b/docs/preview/website/src/content/docs/zh-cn/agents.mdx index 13ec4998..a3018276 100644 --- a/docs/preview/website/src/content/docs/zh-cn/agents.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/agents.mdx @@ -1,6 +1,6 @@ --- title: 智能体 -description: 了解 Herdr 能检测什么、智能体状态如何工作,以及集成如何改进它。 +description: 了解哪些编程智能体可以配合 Herdr 使用(由 Herdr 支持,或自身支持 Herdr),以及智能体状态如何工作。 --- Herdr 为同时运行多个编程智能体而生。每个智能体都待在一个真实的终端窗格里,shell、日志、提示符和运行中的进程都完好无损。Herdr 跟踪哪些窗格里有智能体,把它们的状态汇总到标签页和工作区,让你直接跳到需要关注的窗格,而不是手动轮询每个终端。 @@ -9,46 +9,58 @@ Herdr 为同时运行多个编程智能体而生。每个智能体都待在一 ## 受支持的智能体 -常见编程智能体开箱即用地支持自动检测。重要的区别不在于 Herdr 能不能看到某个智能体,而在于允许哪个信号来决定 `idle`、`working` 和 `blocked`。 +智能体获得 Herdr 支持有两种方式:由 Herdr 支持它,或由它自己支持 Herdr。无论哪种方式,你都能看到每个智能体的 `idle`、`working` 和 `blocked` 状态,在它完成或需要你处理时收到通知,并能在脚本中等待它。 -| 智能体 | 状态权威 | 集成角色 | +其他智能体在 Herdr 窗格中照常运行,只是显示为普通终端。 + +### 由 Herdr 支持 + +Herdr 能识别这些智能体,并从它们在屏幕上绘制的内容读取状态。要在 Herdr 服务器重启后回到同一个会话,请用 `herdr integration install ` 安装该智能体的集成。每个集成会安装什么,见[集成](/zh-cn/docs/integrations/)。 + +| 智能体 | 集成 | 说明 | | --- | --- | --- | -| Pi | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 | -| OMP | 安装后为生命周期钩子 | 状态与会话 | -| GitHub Copilot CLI | 屏幕清单 | 会话 | -| Devin CLI | 屏幕清单 | 会话 | -| Kimi Code CLI | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 | -| Hermes Agent | 屏幕清单 | 会话 | -| Qoder CLI | 屏幕清单 | 会话 | -| Qwen Code | 屏幕清单 | 会话 | -| Letta Code | 屏幕清单 | 会话 | -| Droid | 屏幕清单 | 会话 | -| OpenCode | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 | -| Kilo Code CLI | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 | -| MastraCode | 安装后为生命周期钩子 | 状态与会话 | -| Claude Code | 屏幕清单 | 会话 | -| Codex | 屏幕清单 | 会话 | -| Cursor Agent CLI | 屏幕清单 | 会话 | -| Amp | 屏幕清单 | 无 | -| Grok CLI | 屏幕清单 | 会话 | -| Antigravity CLI | 屏幕清单 | 会话 | -| Kiro CLI | 屏幕清单 | 无 | -| Maki | 屏幕清单 | 无 | -| Muse | 屏幕清单 | 无 | +| Claude Code | `claude` | | +| Codex | `codex` | | +| GitHub Copilot CLI | `copilot` | | +| Cursor Agent CLI | `cursor` | | +| OpenCode | `opencode` | 也上报状态 | +| Pi | `pi` | 也上报状态 | +| OMP | `omp` | 状态需要集成 | +| Droid | `droid` | | +| Devin CLI | `devin` | | +| Kimi Code CLI | `kimi` | 也上报状态 | +| Kilo Code CLI | `kilo` | 也上报状态 | +| Hermes Agent | `hermes` | | +| Qoder CLI | `qodercli` | | +| Qwen Code | `qwen` | | +| Letta Code | `letta` | 仅支持 CLI 安装 | +| MastraCode | `mastracode` | 状态需要集成 | +| Grok CLI | `grok` | | +| Antigravity CLI | `antigravity-cli` | | +| Amp | 无 | 仅状态 | +| Kiro CLI | 无 | 仅状态 | +| Maki | 无 | 仅状态 | +| Gemini CLI | 无 | 仅状态,测试较少 | +| Cline | 无 | 仅状态,测试较少 | -可检测但测试较少: Gemini CLI 和 Cline。不受支持的智能体仍然可以作为普通终端进程正常运行,只是在你添加集成或通过 socket API 上报状态之前,可能得不到丰富的状态。 +### 由智能体自身支持 -## 状态权威 +这些智能体会自己向 Herdr 上报状态。无需安装任何东西,在 Herdr 窗格中运行即可。 -Herdr 首先检测每个窗格的前台进程。之后,每个窗格有且只有一个状态权威。 +- [Crush](https://github.com/charmbracelet/crush) +- Command Code +- Muse +- [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) -对于具备完整生命周期钩子的智能体,当集成已安装并在为运行中的窗格主动上报时,集成就是权威。Herdr 用这些钩子上报来决定 `idle`、`working`、`blocked` 和会话身份。对同一个生命周期权威,它不会再并行运行屏幕清单兜底。这样可以避免出现两个相互竞争的事实来源。 +同时上报恢复命令的智能体,会在 Herdr 服务器重启后回到同一个会话。 -对于没有完整生命周期钩子的智能体,Herdr 识别前台进程,并读取实时的底部缓冲区屏幕快照。它对该快照评估 TOML 清单,来判定 `idle`、`working` 和 `blocked`。对于会发出这些信号的智能体,清单也可以把终端标题和进度 (OSC) 序列作为检测证据;当这些证据不存在时,屏幕规则独自承担检测。 +如果你在开发编程智能体,[为你的智能体添加 Herdr 支持](/zh-cn/docs/add-herdr-support/)介绍了如何加入这个列表。只需调用几次 Herdr 的 CLI 或 socket,不需要修改 Herdr。 -屏幕快照来自窗格缓冲区最近的底部,而不是滚动后的视口。即使你在 Herdr 里向上翻页,检测仍然跟随底部的实时智能体 UI。 +## 状态如何判定 -上表中标为“会话”的集成有意不作为生命周期权威。它们为恢复提供原生会话身份,但它们的钩子并不覆盖整个生命周期,可能漏掉权限审批结果、Esc 中断或其他状态转换。对这些智能体,Herdr 仍然使用屏幕清单检测。 +对于由 Herdr 支持的智能体,Herdr 在每个窗格中找到智能体进程,并读取窗格的实时底部,而不是你滚动到的位置。检测清单中的规则决定该屏幕表示 `idle`、`working` 还是 `blocked`。如果集成也上报状态,Herdr 会使用这些上报,而不是读取屏幕。 + +对于自身支持 Herdr 的智能体,由智能体自己的上报决定状态。 ## 虚拟机与沙箱包装器 @@ -58,9 +70,11 @@ Herdr 首先检测每个窗格的前台进程。之后,每个窗格有且只有 ## blocked 状态 -对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。 +对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对于 Codex 以外的已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。Codex 会回退到 `unknown`,因为在活跃轮次期间和响应结束后,它的标题和输入框可能看起来相同。 -这意味着不常见的新智能体提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。这些交互不会让 Herdr 发送输入或执行破坏性操作;它们只影响可见状态和等待。 +对于其他智能体,不常见的新提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。误判只影响可见状态和等待,不会让 Herdr 发送输入或执行破坏性操作。 + +对于 Codex,可见的旋转指示符或实时活动计时器可以确定 `working`,可见的审批提示可以确定 `blocked`。普通标题、输入框或没有旋转指示符都不能确定一个轮次已经结束。因此,Codex 在响应后可能继续保持 `unknown`,等待 `idle` 或完成也可能超时。托管启动仅使用初始输入框来判断它何时可以接收提示,该观察不会改变轮次状态。 ## 检测清单 @@ -105,17 +119,6 @@ fi 这就是 Herdr 的主要工作流: 启动多个智能体,让它们并行工作,用侧边栏看哪个项目需要决策、哪个还在运行、哪个已经可以审阅。 -## 直接集成 - -为你使用的每个智能体安装集成;它让 Herdr 获得钩子或插件上报,而不是只靠屏幕检测: - -```bash -herdr integration install claude -herdr integration status -``` - -每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。如果你正在构建智能体,[为你的智能体添加 Herdr 支持](/zh-cn/docs/add-herdr-support/)介绍了如何在不为 Herdr 添加原生支持的情况下上报生命周期状态和恢复命令。 - ## 自定义智能体标签 你可以重命名智能体目标的显示名: 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 ae5c3ab4..c71c78c5 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 @@ -49,6 +49,7 @@ herdr api schema --output herdr-api.schema.json ```bash herdr machine list +herdr machine add workbox herdr machine add workbox --label "Build machine" herdr machine rename --label "New name" herdr machine disable @@ -56,7 +57,7 @@ herdr machine enable herdr machine remove ``` -`machine add` 默认使用远程默认会话。只有需要命名会话时才添加 `--remote-session `。`machine list` 支持可选的 `--json` 供脚本使用。完整流程见[连接机器](/zh-cn/docs/connecting-machines/)。 +在交互式终端中，`machine add` 会发现运行中的会话，并在有多个会话运行时让你选择。没有运行中的会话或未安装 Herdr 时使用 `default`；如果查询已安装的二进制文件失败，则需要明确选择。添加 `--remote-session ` 可跳过发现。非交互式命令会使用 `default`，除非提供该选项。`machine list` 支持可选的 `--json` 供脚本使用。完整流程见[连接机器](/zh-cn/docs/connecting-machines/)。 `machine add` 会检查远程 Herdr 是否具备所需能力，仅在必要时征得批准后安装或更新，并在保存配置前启动指定会话的后台服务器。只要兼容，发行版本不必一致。需要批准安装或重启时，请在交互式终端中运行；设置失败或取消时不会保存配置。替换运行中的服务器需要明确批准，默认回答为 No；停止服务器会结束其窗格进程。`machine add` 不会隐式启用实验性实时交接。 @@ -473,6 +474,8 @@ herdr plugin pane close `plugin pane open` 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 `[[panes]]` 命令作为 Herdr 管理的终端窗格启动。清单的默认值是 `overlay`,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页、缩放窗格,或不改变标签页布局的会话级模态 `popup` 打开。`--width` 和 `--height` 以终端单元格数或 `80%` 这样的百分比设置弹窗外层尺寸;省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗不是 Herdr 窗格,不会收到 `HERDR_PANE_ID`,也不参与 pane 或智能体 API。非终端的原生插件窗格是之后的能力面。 +新窗格使用 `TERM_PROGRAM=herdr` 标识自身，并将 `TERM_PROGRAM_VERSION` 设为 Herdr 的版本。它们保留 `TERM=xterm-256color` 和 `COLORTERM=truecolor`。应用显式的启动环境值之前，Herdr 会移除继承的外层终端会话标记（iTerm2、WezTerm、Kitty、Windows Terminal、tmux、screen 和 Zellij）、iTerm2 的 `LC_TERMINAL` 身份，以及已知的 Claude Code、Codex 和 OMP 会话标记。这可防止新窗格冒充最初启动服务器的终端或智能体会话。API 密钥和显示设置等普通环境变量仍会继承，而不会被连接客户端的环境替换。SSH 智能体转发有自己的重连处理。现有窗格进程不受此清理影响。 + `--env KEY=VALUE` 可以在启动进程的命令上重复使用,只作用于新启动的进程。当与调用方提供的环境变量冲突时,`HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_ENTRYPOINT_ID` 和 `HERDR_PLUGIN_CONTEXT_JSON` 等 Herdr 管理的变量保持权威。 ## 读取来源 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 8b8738d6..5885a7ff 100644 --- a/docs/preview/website/src/content/docs/zh-cn/configuration.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/configuration.mdx @@ -73,7 +73,7 @@ headless_rows = 50 default_shell = "nu" ``` -未设置或值为空时，Herdr 会依次使用 `$SHELL`、Unix 上的 `/bin/sh` 或 Windows 上的 PowerShell。该值是可执行文件名或路径，而不是 shell 命令行。现有窗格会保留当前 shell，直到重新创建。自定义命令按键绑定中的字符串在 Unix 上通过 `/bin/sh -c` 执行窗格命令，通过 `/bin/sh -lc` 执行分离式命令；在 Windows 上则通过 `cmd.exe /d /c` 执行。 +未设置或值为空时，Herdr 会在 Unix 上依次使用 `$SHELL` 和 `/bin/sh`。在 Windows 上，如果能从 `PATH` 解析到 `pwsh.exe`（PowerShell 7），则使用它，否则使用系统自带的 `powershell.exe`（Windows PowerShell 5.1）。该值是可执行文件名或路径，而不是 shell 命令行。现有窗格会保留当前 shell，直到重新创建。自定义命令按键绑定中的字符串在 Unix 上通过 `/bin/sh -c` 执行窗格命令，通过 `/bin/sh -lc` 执行分离式命令；在 Windows 上则通过 `cmd.exe /d /c` 执行。 设置 Herdr 如何启动新建交互式窗格的 shell： @@ -142,6 +142,15 @@ navigate_pane_down = "ctrl+j" split_horizontal = "prefix+minus" ``` +需要通过多个按键进入前缀模式时，`keys.prefix` 也接受数组。例如，可让 macOS 和远程 Linux 机器共享同一份配置： + +```toml +[keys] +prefix = ["ctrl+space", "ctrl+s"] +``` + +配置的每个前缀都会进入同一个前缀模式，并可触发所有 `prefix+...` 动作。第一项是状态栏中显示的主前缀；应用内 `prefix+?` 帮助面板会列出全部前缀。 + 默认键位以前缀为主，因此 Herdr 不会抢占 shell、编辑器、tmux 或终端应用的输入。在[配置参考](/docs/config-reference/)中搜索 `keys.` 可查看每个动作及其默认绑定。应用内帮助面板可通过 `prefix+?` 打开，其中会显示当前生效的绑定。 当一个动作需要多个快捷键时，绑定也可以是数组： @@ -244,6 +253,8 @@ name = "catppuccin" 在[配置参考](/docs/config-reference/)中搜索 `theme.name` 可查看所有内置主题。如果想让 Herdr UI 颜色跟随宿主终端的 ANSI 调色板，请使用 `terminal`。 +在 Unix 上，Herdr 还会在调整大小或收到 `SIGWINCH` 后重绘时重新读取宿主终端的颜色。如果主题切换器通过 OSC 更改终端颜色却不发送明暗通知，请在应用新调色板后执行 `kill -WINCH `。目标应是已连接的 Herdr 客户端，而不是服务器；现有窗格会继续运行。直接通过 `herdr terminal attach` 连接的会话会把调色板查询交给所连接的应用。 + 要让 Herdr 在宿主终端报告明暗外观变化时自动切换自身的 UI 主题，请启用主题自动切换： ```toml @@ -508,9 +519,19 @@ claude = "on" ## Kitty graphics -Herdr 默认在兼容的外层终端中渲染窗格图像。图像放置区域与弹窗、菜单或通知重叠时，Herdr 会暂时隐藏整个图像放置区域，而不是只裁剪重叠部分。未被遮挡的图像保持可见，被隐藏的图像放置区域在遮挡消失后恢复显示。图像不会随对话框背景一起变暗。 +应用和插件通过窗格终端输出中发出的标准 Kitty graphics 协议进行集成。Herdr 默认在兼容的外层终端中渲染这些图像。外部 socket 窗格覆盖层 API 已被移除，也没有替代的 socket 图像 API。 -要禁用图形渲染和窗格图形 API，请设置： +弹窗、菜单和通知会在其覆盖区域周围裁剪图像；每幅图像的其余部分仍然可见，覆盖层关闭后，被遮挡的部分会恢复显示。图像不会随对话框背景一起变暗。 + +Herdr 会自动选择符合条件的文件传输方式，无需更改应用或切换环境变量。在本地 Unix Ghostty 客户端上，它可以通过临时文件发送图像数据，而不是将其编码到终端输出中。系统会先用一个小型文件读取探测来检查支持情况。其他终端、通过 SSH 启动的客户端和嵌套多路复用器仍使用内联输出进行最后一跳优化。 + +对于符合条件的本地客户端，原生 RGBA 图像从服务器传到客户端时使用 Herdr 所有的快照路径，而不是像素字节。不支持的客户端和失败的传输会回退到内联传送。远程服务器路径绝不会转发到本地终端。图像放置、裁剪和可见性仍由 Herdr 控制。 + +在 Linux 上，Herdr 读取整文件、未压缩 RGBA 上传的像素前，可以使用写时复制快照。这要求文件系统支持克隆到 Herdr 的私有 `/var/tmp` 存储。不支持的文件系统、临时文件上传、共享内存和其他格式会使用普通加载器。每个快照上限为 16 MiB，总上限为 64 MiB；动画和不受支持的客户端会在需要时读取像素。Herdr 接受图像后绝不会依赖可变的生产者路径。 + +PNG 上传仍会进行完整解码和验证。Herdr 不会把损坏图像的验证推迟到外层终端。 + +要禁用 Kitty graphics 渲染，请设置： ```toml [terminal] @@ -519,7 +540,7 @@ kitty_graphics = false 为兼容现有配置，旧的 `experimental.kitty_graphics` 设置仍然可用。若两者同时设置，`terminal.kitty_graphics` 优先。 -更改此设置后，需要重启受影响的 Herdr 服务器或重新连接客户端。在远程会话中，服务器端设置控制窗格图形解析和 API 可用性，本地客户端设置控制向外层终端输出图形。 +更改此设置后，需要重启受影响的 Herdr 服务器或重新连接客户端。在远程会话中，服务器端设置控制 Kitty graphics 解析，本地客户端设置控制向外层终端输出图形。 ## 智能体会话恢复 diff --git a/docs/preview/website/src/content/docs/zh-cn/connecting-machines.mdx b/docs/preview/website/src/content/docs/zh-cn/connecting-machines.mdx index 722adeed..116cecbb 100644 --- a/docs/preview/website/src/content/docs/zh-cn/connecting-machines.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/connecting-machines.mdx @@ -7,6 +7,8 @@ description: 在一个 Herdr 窗口中使用 Local 和已保存的 SSH 机器， 每台机器保留自己的 Herdr 服务器、会话和进程。一台机器断线不会影响其他连接。 +Herdr 会请求 SSH 压缩，以减少受限连接上的屏幕更新流量。这适用于较旧的兼容 Herdr 服务器，也不会改变按键或其他输入的传送方式。Herdr 的 `-C` 选项会覆盖 SSH 配置中的 `Compression no`。如果 SSH 通过外部 ControlMaster 复用现有连接，该连接会保留原来的压缩设置。 + ### 恢复 SSH 认证 在 Linux 和 macOS 上，启用 `remote.manage_ssh_config=true` 后，添加机器、侧边栏和 API 操作共享已批准的 OpenSSH 连接。运行 `herdr machine status [] [--json]` 可进行新的非交互式检查。**reachable** 表示远程 Herdr 当前可用，不代表每个 TUI 都已连接。在终端运行 `herdr machine reconnect ` 完成原生 SSH 认证并验证已保存的机器；该命令不会安装或更新 Herdr。已打开的客户端会在 30 秒内重试，无需重启。点击 **`! auth`**、**`! error`** 或失败后的重连状态，会显示包含最新错误及 CLI 命令的通知，不会打开认证弹窗。机器行其余部分仍用于展开或折叠。 @@ -30,17 +32,23 @@ ssh workbox 请在交互式终端中运行，以便 Herdr 在安装或替换内容之前询问： ```bash -herdr machine add workbox --label "Build machine" +herdr machine add workbox ``` -这会使用远程默认会话。一个机器配置只对应一个远程会话，不会汇总该主机的所有会话。 +在交互式终端中，Herdr 会发现运行中的会话：只有一个会话运行时自动选择；有多个时，可用 Up/Down 选择并按 Enter 确认。按 Esc 或 Ctrl+C 取消。查询成功但没有运行中的会话时，设置使用 `default`。未找到 Herdr 安装时，设置会提议为 `default` 安装。如果已安装的二进制文件无法报告会话，设置会报告错误；可传入 `--remote-session ` 明确选择会话。 -如需命名会话，再添加可选的 `--remote-session`： +默认会话在侧边栏中显示为 `workbox`，即去掉所有 `user@` 前缀的 SSH 主机名。添加 `--label "Build machine"` 可选择其他名称。一个机器配置只对应一个远程会话，不会汇总该主机的所有会话。非交互式命令使用 `default`，除非提供 `--remote-session`。 + +要跳过发现并使用指定会话，请添加 `--remote-session`： ```bash -herdr machine add workbox --label "Build machine" --remote-session agents +herdr machine add workbox --remote-session agents ``` +未提供 `--label` 时，这台机器显示为 `workbox/agents`。如果默认名称已被占用，`machine add` 会要求你传入 `--label`。 + +在 Windows 服务器上，设置还会检查 SSH 用户拥有的 Herdr 进程所使用的可执行文件。它会先验证其能力再复用，因此即使 SSH 的 `PATH` 指向较旧的安装，也能使用兼容的运行中构建。 + Herdr 分别检查已安装的二进制文件和运行中的服务器，并在保存配置之前启动目标后台服务器。客户端和服务器版本只要兼容，就不必一致。未安装或不兼容时会进入需要批准的设置流程。如果必须替换运行中的服务器，会先询问是否停止它及其窗格进程，再启动兼容的服务器。默认回答为 No；同时需要安装和替换时，一次确认涵盖两项操作。`machine add` 不使用实验性的实时交接。取消或设置失败时，不会保存配置。 运行 `herdr` 打开 UI。如果本地客户端已经打开，新增或启用的机器通常会在一秒内出现并在后台连接，不改变当前选择。切换机器期间的配置变化会在切换完成后应用。设置结束后，远程服务器仍会运行。 @@ -95,6 +103,10 @@ herdr --remote workbox 认证失败时，先检查普通 SSH。对于有口令的私钥，请在启动 Herdr 的非交互式后台连接前用 `ssh-add` 加载。 +如需在远程窗格中进行 Git 认证或 SSH 签名，请在 SSH 配置中为可信主机启用 `ForwardAgent yes`。Herdr 不会替你启用转发。如果会话启动时带有智能体，更新后的 Linux 和 macOS 服务器会为窗格提供稳定的智能体地址，因此在 `--remote` 或已保存机器重新连接后，现有窗格和新窗格都能使用转发的智能体。可用的继承智能体或较早的连接优先于后续客户端和临时设置检查；如果它消失，另一个实时连接可以提供智能体。 + +这需要更新远程服务器，而不只是本地客户端。未带智能体启动的本地会话不会更改 `SSH_AUTH_SOCK`。在服务器更新前或会话首次获得智能体前创建的窗格会保留原来的环境，需要重新创建一次才能继承稳定地址。较旧的兼容服务器和未转发智能体的连接仍可正常连接。 + ## 设置与自动化 UI 默认使用客户端本地的主题、侧边栏设置和按键绑定。选中服务器公布的自定义命令和插件仍在那里运行。Herdr 不会将本地插件、配置、可执行文件或机密复制到 SSH 主机。远程缺少命令时会明确报错。编辑客户端设置后，使用 UI 中的 `reload config`；参见[配置](/zh-cn/docs/configuration/)。 @@ -107,6 +119,8 @@ UI 默认使用客户端本地的主题、侧边栏设置和按键绑定。选 配置只保存不透明 ID、标签、SSH 目标、明确的远程会话名和启用状态。Herdr 不会将密码、私钥、智能体票据或 SSH 控制套接字存入机器目录。认证仍由 OpenSSH 处理。 +Herdr 会另外记住每台机器的远程操作系统和解析后的可执行文件路径，让重复的 `--machine` 命令可以跳过发现。现有配置会在首次使用时补充缺失信息。该缓存是可选的：缓存文件缺失、无效或不可写都不会妨碍命令运行。命令仍会检查实时服务器兼容性。如果缓存的可执行文件不存在或不再支持 API 转发，Herdr 会在最初的只读检查期间重新发现它；对于可能已经更改远程状态的命令，Herdr 绝不会自动重试。 + 客户端与服务器协商兼容性，不要求版本完全相同。保存机器的连接还需要服务器支持 `surface_interest` 和 `health_check` 能力。缺少这些能力的旧服务器，即使能独立连接，也会显示 Attention，直到明确更新。其他缺失的方法只禁用对应操作。 更新兼容客户端不会替换远程服务器或停止其智能体。需要新的服务器行为时，请明确更新该服务器。正常替换会在停止服务器及其窗格进程之前询问。 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 93885224..1d44c225 100644 --- a/docs/preview/website/src/content/docs/zh-cn/install.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/install.mdx @@ -149,6 +149,8 @@ Windows 的常规使用建议选择稳定版。预览版能更早获得修复, herdr update --handoff ``` +当两个服务器都支持智能体状态传输时,实时交接会保留钩子上报的智能体状态,直到下一次上报到达。从较旧服务器交接时,运行中的智能体可能暂时显示为 idle。 + 实时交接不适用于 Homebrew、mise 或 Nix 的包管理器更新。这些安装先用包管理器更新,再重新运行 Herdr,用更新后的客户端连接。兼容的旧服务器会继续运行。只有需要新版本的服务器端改动时,才稍后用 `herdr server stop` 或 `herdr session stop ` 重启它。 ## 系统要求 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 0fc3d2c0..20ca0aab 100644 --- a/docs/preview/website/src/content/docs/zh-cn/integrations.mdx +++ b/docs/preview/website/src/content/docs/zh-cn/integrations.mdx @@ -3,7 +3,7 @@ title: 集成 description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、MastraCode、Antigravity CLI 和 Grok CLI 安装 Herdr 集成。 --- -Herdr 自动检测受支持的智能体。官方集成可以额外提供用于恢复的原生会话身份、生命周期状态上报,或两者兼有。 +Herdr 会自动检测它支持的智能体。安装智能体的集成后,Herdr 可以在服务器重启后恢复同一个会话。部分集成还会直接上报智能体的状态。哪些智能体由 Herdr 支持、哪些智能体自己支持 Herdr,见[智能体](/zh-cn/docs/agents/)。 当你想要智能体原生会话恢复、直接生命周期上报,或两者都要时,使用集成。完整的状态权威模型见[智能体](/zh-cn/docs/agents/)。 @@ -59,16 +59,9 @@ Herdr 对 Linux/macOS 上的集成配置和所有平台的新文件使用原子 ## Herdr 如何使用集成 -Herdr 以两种不同方式使用集成: +每个集成都会告诉 Herdr 智能体当前所在的会话,这样 Herdr 就能在服务器重启后恢复它。用 `[session] resume_agents_on_restore = false` 可以关闭。 -| 集成类型 | 智能体 | 效果 | -| --- | --- | --- | -| 生命周期权威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、MastraCode | 已安装且在为该窗格主动上报时,由钩子或插件事件决定 `idle`、`working` 和 `blocked`。对同一个生命周期权威,Herdr 不再使用屏幕清单兜底。 | -| 会话身份 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、Hermes Agent、Antigravity CLI、Grok CLI | 集成上报用于恢复的原生会话引用。状态仍来自 Herdr 的屏幕清单检测。 | - -自定义集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。它们不需要内置到 Herdr 中,也不要求 Herdr 识别智能体的可执行文件。 - -一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Qwen Code、Letta Code、Cursor Agent CLI、Grok CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI、MastraCode 和 Antigravity CLI 的窗格。 +Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI 和 MastraCode 的集成还会上报智能体的状态。在它们上报期间,Herdr 使用这些上报,而不是读取屏幕。其他集成则把状态交给屏幕检测。 原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 `2`、OMP 版本 `3`、Claude Code 版本 `6`、Codex 版本 `5`、GitHub Copilot CLI 版本 `2`、Devin CLI 版本 `2`、Droid 版本 `2`、Kimi Code CLI 版本 `3`、Qoder CLI 版本 `2`、Qwen Code 版本 `1`、Letta Code 版本 `1`、Cursor Agent CLI 版本 `1`、Grok CLI 版本 `2`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `5`、MastraCode 版本 `1`、Antigravity CLI 版本 `1`。用 `herdr integration status` 查看已安装版本。 @@ -202,7 +195,7 @@ herdr integration install opencode 该集成支持 OpenCode V1 `1.18.29` 及更高版本，以及 OpenCode V2（已验证 beta `19242`）。OpenCode 配置目录必须已经存在。Herdr 将服务端入口安装到 `~/.config/opencode/plugins/herdr-agent-state.js`，并在该配置目录安装共享 TUI 插件 `herdr-tui-session.js` 和 V2 TUI 入口 `herdr-opencode/tui.js`。 -安装会在 `tui.jsonc` 中注册 V1 TUI 插件，并在 `cli.json` 中注册 V2 TUI 插件，同时保留其他设置和插件。如果 OpenCode 仍有 V1 TUI 偏好需要迁移(`tui.json` 或 `kv.json`),Herdr 会推迟注册，以便首次启动时执行迁移；此时请先启动一次 `opencode2`，然后重新安装集成。否则 Herdr 会创建 `cli.json` 并注册插件。安装后请重启 OpenCode TUI。卸载会删除受管理的插件文件及其配置条目。 +安装会在 `tui.jsonc` 中注册 V1 TUI 插件，并在 `cli.json` 中注册 V2 TUI 插件，同时保留其他设置和插件。`tui.json` 中已有的 V1 注册也视为已安装,会直接复用而不创建 `tui.jsonc`。卸载会从两个 TUI 配置文件中移除 Herdr 注册,同时保留文件和其他设置。如果 OpenCode 仍有 V1 TUI 偏好需要迁移(`tui.json` 或 `kv.json`),Herdr 会推迟注册，以便首次启动时执行迁移；此时请先启动一次 `opencode2`，然后重新安装集成。否则 Herdr 会创建 `cli.json` 并注册插件。安装后请重启 OpenCode TUI。卸载会删除受管理的插件文件及其配置条目。 V2 生命周期上报在窗格本地的 TUI 中运行。即使多个窗格共享同一个 OpenCode 服务端，事件也只归属于该 TUI 选中的根会话。完成和中断会清除工作状态；待处理的权限请求、表单以及执行失败会使窗格保持阻塞。V2 Mini 和无界面客户端不运行 TUI 插件，因此不提供此生命周期上报。 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 e26c259e..de5c7e7e 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 @@ -482,6 +482,8 @@ Herdr 在本地 socket 上使用换行分隔的 JSON。在 Unix 上,那个 socke {"id":"req_1","result":{"type":"pong"}} ``` +对于已进入 JSON 解码的请求行,错误响应也会回显请求的 `id`,包括方法或参数无效的情况。如果 JSON 无效或顶层没有明确的字符串 `id`,错误响应会使用空 `id`。无效 UTF-8 等传输错误可能直接关闭连接而不返回响应。 + 事件订阅在初始响应之后保持连接打开。 ## Socket 路径 @@ -541,7 +543,7 @@ Herdr 在本地 socket 上使用换行分隔的 JSON。在 Unix 上,那个 socke } ``` -两个方法都接受可选的 `resume_argv` 数组,内容是 Herdr 服务器重启后恢复上报者当前会话的命令。第一个元素必须是普通命令名而不是路径,并且任何元素都不能包含撇号;无效值会以 `invalid_resume_argv` 失败,该次上报不会生效。自定义智能体必须先通过 `pane.report_agent` 持有窗格才能附加命令,否则请求会以 `resume_not_accepted` 失败。Herdr 只在同一 `source` 和 `agent` 持有窗格时保留该命令,并且它优先于 Herdr 为该智能体内置的恢复命令。旧版 Herdr 会忽略这个字段。 +两个方法都接受可选的 `resume_argv` 数组,内容是 Herdr 服务器重启后恢复上报者当前会话的命令。第一个元素必须是普通命令名而不是路径。该数组最多允许 64 个元素,总大小不超过 8 KiB,并且任何元素都不能包含撇号或控制字符;无效值会以 `invalid_resume_argv` 失败,该次上报不会生效。自定义智能体必须先通过 `pane.report_agent` 持有窗格才能附加命令,否则请求会以 `resume_not_accepted` 失败。Herdr 只在同一 `source` 和 `agent` 持有窗格时保留该命令,并且它优先于 Herdr 为该智能体内置的恢复命令。旧版 Herdr 会忽略这个字段。 ```json { @@ -638,7 +640,7 @@ workspace 的 get/list 响应会公开生成的 `tokens` 映射,空间侧边栏 } ``` -第一个响应确认订阅。之后的行是推送的事件。生命周期事件订阅从请求被接受时开始,不会重放在此之前保留的事件。 +第一个响应确认订阅。之后的行是推送的事件。所有条目都必须有效:如果引用的任何窗格不存在,Herdr 会拒绝整个请求,返回错误并关闭连接。请刷新窗格列表后重试,不要假定其他条目已经订阅。生命周期事件订阅从请求被接受时开始,不会重放在此之前保留的事件。 生命周期和智能体状态事件按有界批次发送,每个订阅内保持事件顺序。事件历史不是持久日志。如果订阅者落后到保留范围之外,包括订阅初始化期间,服务器会发送包含原请求 `id` 和 `error.code: "events_lost"` 的错误响应,然后关闭该订阅连接,而不是静默跳过缺失事件后继续发送。其他客户端的连接不受影响。各类事件共享历史缓冲,因此即使被淘汰的事件可能不匹配此订阅的过滤条件,仍会报告溢出。