diff options
| author | github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> | 2026-08-03 19:00:20 +0000 |
|---|---|---|
| committer | github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> | 2026-08-03 19:00:20 +0000 |
| commit | 3642e67c7b9c1d8608d72f288e80b410c602e55c (patch) | |
| tree | 31e956f8d0ce3ffa7ad06495c6523cc3c7b3a3a5 /website/src/content/docs/zh-cn | |
| parent | 346411fa21afd297f5ed3b3fa56f9e3fbf7654b7 (diff) | |
docs: update website manifest for v0.8.0
Diffstat (limited to 'website/src/content/docs/zh-cn')
20 files changed, 0 insertions, 3746 deletions
diff --git a/website/src/content/docs/zh-cn/agent-automation.mdx b/website/src/content/docs/zh-cn/agent-automation.mdx deleted file mode 100644 index c8ec6ce9..00000000 --- a/website/src/content/docs/zh-cn/agent-automation.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: 智能体自动化 -description: 使用 Herdr 的布局、窗格和智能体原语,从脚本或其他智能体协调编码智能体。 ---- - -Herdr 可以作为编码智能体的自动化层。脚本可以控制智能体,一个智能体也可以给其他智能体分配工作、检查状态并收集结果。关键是为任务选择正确的原语。 - -## 三种原语 - -| 原语 | 职责 | -| --- | --- | -| 布局（`workspace`、`tab` 和窗格拓扑） | 创建和组织终端位置。 | -| 窗格 | 控制原始终端:运行命令、发送输入、读取输出和等待输出。 | -| 智能体 | 按名称或窗格以及生命周期状态控制已识别的编码智能体。 | - -无论是否包含智能体,窗格都可以存在。智能体是 Herdr 在窗格中识别出的当前进程。因此,`agent start` 需要一个现有 shell 窗格,绝不会创建、拆分或移动布局。 - -创建工作区时也会创建第一个标签页和根窗格;创建标签页时会创建它的根窗格。第一个进程应使用返回的窗格 ID,只有布局需要另一个终端时才进行拆分。 - -创建命令输出 JSON。请从响应中读取 ID,不要猜测: - -```bash -created=$(herdr workspace create --cwd ~/project --label api --no-focus) -pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id') - -split=$(herdr pane split "$pane_id" --direction right --no-focus) -review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id') -``` - -`workspace create` 返回 `.result.workspace`、`.result.tab` 和 `.result.root_pane`;`tab create` 返回 `.result.tab` 和 `.result.root_pane`;`pane split` 把新窗格返回为 `.result.pane`。 - -把窗格移动到另一个工作区会改变带工作区前缀的窗格 ID。执行 `pane move` 后,请继续使用 `.result.move_result.pane.pane_id`;旧值保留在 `.result.move_result.previous_pane_id`。运行中的进程会保留启动时的 Herdr 环境,但旧的 `HERDR_PANE_ID` 会继续作为该终端的别名,所以 `--current` 仍可安全使用。移动后发起的新命令仍可通过智能体名称解析,但已经进行中的等待会以 `agent_not_running` 结束。 - -对于 shell、测试、服务器、CI 监视器和其他普通终端进程,使用窗格命令。当 Herdr 需要理解正在运行的是哪个智能体,或它处于 `working`、`blocked`、`done`、`idle`、`unknown` 中的哪个状态时,使用智能体命令。 - -## 智能体身份与启动 - -`w1:p2` 这样的窗格 ID 标识终端位置。`reviewer` 这样的智能体名称是该窗格中当前智能体的便捷别名。名称必须匹配 `[a-z][a-z0-9_-]{0,31}`,并在实时智能体中唯一。智能体退出、被释放或被替换时,别名会被清除;它不会永久重命名窗格。 - -智能体命令既可以接受唯一的实时名称,也可以接受当前托管该智能体的窗格 ID。 - -可用的 shell 窗格必须停在交互式 shell 提示符,由 shell 自身占用前台,没有正在前台运行的命令、编辑器或智能体。调用 `agent start` 前先让窗格回到提示符。 - -`--kind` 选择受支持的智能体及其标准可执行文件。支持的 kind 是 `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli` 和 `maki`。`--` 后的参数会原样传给该可执行文件。 - -`agent start` 只有在 Herdr 于同一终端检测到预期智能体,并确认它可接受交互输入后才返回。默认等待启动 30 秒;`--timeout` 必须大于 3000 且不超过 300000 毫秒。 - -```bash -herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4 -``` - -手动启动的智能体也会被自动检测,可以用窗格 ID 指定。当需要一个稳定、易读的目标时,给它命名: - -```bash -herdr agent get w1:p2 -herdr agent rename w1:p2 reviewer -``` - -## 选择控制界面 - -| 目标 | 命令 | -| --- | --- | -| 运行并提交 shell 命令 | `pane run` | -| 发送不带 Enter 的纯文本 | `pane send-text` | -| 发送终端按键或修饰键组合 | `pane send-keys` | -| 等待文本或正则表达式 | `pane wait-output` | -| 在现有窗格中启动受支持的智能体 | `agent start` | -| 提交提示,并可选择等待 | `agent prompt` | -| 向智能体交互界面发送按键 | `agent send-keys` | -| 等待智能体生命周期状态 | `agent wait` | - -`agent prompt` 会提交文本和编码后的 Enter,并遵循终端当前的 bracketed paste 模式。即使智能体正在 working 也可以提交。使用 `agent send-keys` 进行 `esc`、`up`、`enter`、`ctrl+c` 等交互;`escape` 也是 `esc` 的别名。只有在明确需要原始终端控制时才使用窗格输入命令。 - -窗格输入直接指定终端,不关心当前进程。智能体输入会解析实时智能体;如果该智能体已不再控制此窗格,操作会被拒绝。 - -`agent prompt --wait` 会立即提交提示。智能体从非 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` 一起使用。 - -`idle` 表示智能体正等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,但用于后台工作完成后,直到该标签页获得焦点或 `pane focus` / `agent focus` 指向它。仅通过 CLI 读取不会把它标记为已查看。`blocked` 表示 Herdr 识别到了审批或提问界面。`unknown` 表示智能体存在,但 Herdr 无法可靠判断其生命周期;它不代表工作成功完成。区别重要时,请指定精确的 `--until` 状态。 - -`pane wait-output` 不解释智能体生命周期。它轮询选定的终端快照并立即进行第一次搜索,所以已经存在的文本也会匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制;`--regex` 使用 Rust 正则表达式语法并逐行匹配。 - -在 CLI 中,`pane read` 和 `agent read` 都直接打印终端文本。默认输出去除 ANSI 转义的 UTF-8 文本;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留终端转义。`detection` 来源始终是纯文本。对 recent 类来源,`--lines N` 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 `visible` 和 `detection`,省略 `--lines` 会返回完整快照,指定时保留按换行分隔的最后 N 行。socket API 在 `.result.read.text` 返回文本。 - -## 已知注意事项:备用屏幕输出 - -Claude Code 和 OpenCode 等全屏智能体可能会在终端的备用屏幕中绘制。备用屏幕中的行不会进入 Herdr 的主机回滚缓冲区。`--lines` 只能请求窗格当前屏幕和主机回滚缓冲区中现有的更多行,不能生成缺失的历史。如果增大 `--lines` 后仍没有返回更多回复文本,该窗格很可能正在使用备用屏幕,且那些回复行已不再保留。字体较大或窗格较小时更容易遇到此限制。 - -可以要求智能体简洁回复、扩大窗格或使用较小字体,也可以使用智能体自身的记录和滚动控件。在智能体内部滚动后,使用 `--source visible` 读取它当前绘制的页面。 - -在这次读取失败后,可以让智能体把完整回复以 Markdown 格式写入临时目录,只回复文件路径,然后直接读取该文件。仅将此方法用作后备方案;不要在初始提示中要求文件输出。 - -成功的 `agent start`、`agent prompt` 和 `agent wait` 会在 `.result.agent` 返回当前智能体。`pane wait-output` 返回 `.result.pane_id`、`.result.matched_line` 以及位于 `.result.read` 的匹配快照。 - -等待命令没有默认超时,可能无限等待。超时或服务器错误会把 JSON 错误写到 stderr 并以状态 1 退出;CLI 语法错误以状态 2 退出。 - -## 示例 - -启动辅助智能体,分配工作,并等待该工作结束: - -```bash -split=$(herdr pane split --current --direction right --no-focus) -review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id') -herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4 -herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000 -herdr agent read reviewer --source recent-unwrapped --lines 120 -``` - -等待智能体请求输入,检查内容,再操作其交互界面: - -```bash -herdr agent wait reviewer --until blocked --timeout 120000 -herdr agent read reviewer --source recent-unwrapped --lines 80 -herdr agent send-keys reviewer esc -``` - -运行普通进程并等待输出,而不把它当作智能体: - -```bash -herdr pane run w1:p3 "just test --watch" -herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000 -``` - -完整命令和选项列表见 [CLI 参考](/zh-cn/docs/cli-reference/)。Shell 补全也能以交互方式显示同一命令树。 diff --git a/website/src/content/docs/zh-cn/agent-skill.mdx b/website/src/content/docs/zh-cn/agent-skill.mdx deleted file mode 100644 index 98e5d529..00000000 --- a/website/src/content/docs/zh-cn/agent-skill.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: 智能体技能文件 -description: 为 Claude Code 或其他编程智能体安装 Herdr 使用说明。 ---- - -Herdr 提供了一个可复用的智能体技能文件: [`skills/herdr/SKILL.md`](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md)。 - -把这个文件安装到任何支持可复用技能或自定义指令的编程智能体中。这份技能教智能体如何在 Herdr 窗格内部控制 Herdr。 - -Herdr 还提供了另一份用途不同的指南: [`herdr.dev/agent-guide.md`](https://herdr.dev/agent-guide.md),用于让智能体帮助人类学习、安装或排查 Herdr。技能是给操作 Herdr 的智能体用的;指南是给教人类的智能体用的。 - -## 这份技能做什么 - -这份技能告诉智能体: 当 `HERDR_ENV=1` 已设置时,使用 `herdr` CLI。这意味着智能体运行在 Herdr 管理的窗格内,可以安全地与本地 Herdr socket 通信。 - -安装技能后,智能体可以: - -- 查看工作区、标签页、窗格和相邻的智能体 -- 分割窗格并在不抢占焦点的情况下运行命令 -- 读取窗格输出和最近的日志 -- 等待服务器、测试或另一个智能体完成 -- 在相邻窗格中启动辅助智能体 - -这份技能不是独立的应用或服务,它只是一份给智能体看的 markdown 指令文件。 - -## 安装 - -用 `npx skills` 安装技能: - -```bash -npx skills add herdrdev/herdr --skill herdr -g -``` - -如果你是在该技能仍位于仓库根目录时安装的，请重新运行一次此 add 命令，而不要使用 `skills update`。add 命令会替换原先过大的副本并记录新位置。 - -`-g` 参数为受支持的智能体全局安装。省略 `-g` 则安装到当前项目。 - -以仓库中的副本作为手动兜底和事实来源: - -```text -https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md -``` - -对于有技能系统的智能体,把这个文件安装为名为 `herdr` 的技能。对于没有技能系统的智能体,把文件内容粘贴到智能体的项目指令或用户指令中。 - -安装完成后,在 Herdr 内启动智能体: - -```bash -herdr -claude -``` - -也可以在 Herdr 窗格里使用任何其他编程智能体。重点是智能体进程要运行在 Herdr 内部,这样 `HERDR_ENV=1` 才可用。 - -## 安全规则 - -这份技能以一条护栏开头: 如果 `HERDR_ENV=1` 未设置,智能体应当停下来,并说明自己没有运行在 Herdr 管理的窗格内。 - -这可以防止 Herdr 外部的智能体试图控制一个不属于它的会话。 - -## 面向智能体的参考 - -完整的命令指南就在技能文件本身。它涵盖窗格 ID、`pane split`、`pane run`、`pane read`、`pane wait-output`、`agent wait`、工作区和标签页命令,以及协作配方。 - -在这里阅读源文件: - -[在 GitHub 上打开 `SKILL.md` →](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md) diff --git a/website/src/content/docs/zh-cn/agents.mdx b/website/src/content/docs/zh-cn/agents.mdx deleted file mode 100644 index fb478081..00000000 --- a/website/src/content/docs/zh-cn/agents.mdx +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: 智能体 -description: 了解 Herdr 能检测什么、智能体状态如何工作,以及集成如何改进它。 ---- - -Herdr 为同时运行多个编程智能体而生。每个智能体都待在一个真实的终端窗格里,shell、日志、提示符和运行中的进程都完好无损。Herdr 跟踪哪些窗格里有智能体,把它们的状态汇总到标签页和工作区,让你直接跳到需要关注的窗格,而不是手动轮询每个终端。 - -要从脚本或另一个智能体协调它们,请参阅[智能体自动化](/zh-cn/docs/agent-automation/)。 - -## 受支持的智能体 - -常见编程智能体开箱即用地支持自动检测。重要的区别不在于 Herdr 能不能看到某个智能体,而在于允许哪个信号来决定 `idle`、`working` 和 `blocked`。 - -| 智能体 | 状态权威 | 集成角色 | -| --- | --- | --- | -| Pi | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 | -| OMP | 安装后为生命周期钩子 | 状态 | -| GitHub Copilot CLI | 屏幕清单 | 会话 | -| Devin CLI | 屏幕清单 | 会话 | -| Kimi Code CLI | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 | -| Hermes Agent | 安装后为生命周期钩子;否则为屏幕清单 | 状态与会话 | -| Qoder CLI | 屏幕清单 | 会话 | -| Droid | 屏幕清单 | 会话 | -| OpenCode | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 | -| Kilo Code CLI | 安装后为生命周期插件;否则为屏幕清单 | 状态与会话 | -| MastraCode | 安装后为生命周期钩子 | 状态与会话 | -| Claude Code | 屏幕清单 | 会话 | -| Codex | 屏幕清单 | 会话 | -| Cursor Agent CLI | 屏幕清单 | 会话 | -| Amp | 屏幕清单 | 无 | -| Grok CLI | 屏幕清单 | 无 | -| Antigravity CLI | 屏幕清单 | 无 | -| Kiro CLI | 屏幕清单 | 无 | -| Maki | 屏幕清单 | 无 | - -可检测但测试较少: Gemini CLI 和 Cline。不受支持的智能体仍然可以作为普通终端进程正常运行,只是在你添加集成或通过 socket API 上报状态之前,可能得不到丰富的状态。 - -## 状态权威 - -Herdr 首先检测每个窗格的前台进程。之后,每个窗格有且只有一个状态权威。 - -对于具备完整生命周期钩子的智能体,当集成已安装并在为运行中的窗格主动上报时,集成就是权威。Herdr 用这些钩子上报来决定 `idle`、`working`、`blocked` 和会话身份。对同一个生命周期权威,它不会再并行运行屏幕清单兜底。这样可以避免出现两个相互竞争的事实来源。 - -对于没有完整生命周期钩子的智能体,Herdr 识别前台进程,并读取实时的底部缓冲区屏幕快照。它对该快照评估 TOML 清单,来判定 `idle`、`working` 和 `blocked`。对于会发出这些信号的智能体,清单也可以把终端标题和进度 (OSC) 序列作为检测证据;当这些证据不存在时,屏幕规则独自承担检测。 - -屏幕快照来自窗格缓冲区最近的底部,而不是滚动后的视口。即使你在 Herdr 里向上翻页,检测仍然跟随底部的实时智能体 UI。 - -Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI 和 Cursor Agent CLI 的集成有意不作为生命周期权威。它们为恢复提供原生会话身份,但它们的钩子并不覆盖整个生命周期,可能漏掉权限审批结果、Esc 中断或其他状态转换。对这些智能体,Herdr 仍然使用屏幕清单检测。 - -## 虚拟机与沙箱包装器 - -在 Linux 和 macOS 上,宿主可见的包装器可能会向 Herdr 隐藏真实的智能体进程。在包装器命令上设置 `HERDR_AGENT=<agent>`,告诉 Herdr 应使用哪个已有智能体的屏幕清单。例如,在 Linux 上运行 `HERDR_AGENT=claude fence -- claude`,或在 macOS 上运行 `HERDR_AGENT=claude nono run --profile claude-code -- claude`。这个提示的作用范围只限于该前台进程;仅在 VM 或容器内部设置时 Herdr 无法看到它,而且除非所有继承的前台进程都应被视为该智能体,否则不要全局 export。 - -## blocked 状态 - -对屏幕清单类智能体,blocked 检测刻意从严。只有当实时底部缓冲区快照匹配已知可见的审批、提问或权限 UI 时,Herdr 才标记 `blocked`。对已知智能体,如果没有任何清单规则匹配,Herdr 会回退到 `idle`,并在 explain 输出中把该回退标记为 `default_known_agent_idle_fallback`。 - -这意味着不常见的新智能体提示可能一开始显示为 `idle` 而不是 `blocked`,直到 Herdr 学会那种屏幕形态。这些交互不会让 Herdr 发送输入或执行破坏性操作;它们只影响可见状态和等待。 - -## 检测清单 - -内置清单打包在 Herdr 内部。Herdr 还会向 herdr.dev 检查远程清单更新,并自动应用有效的按智能体规则更新,不需要重启 Herdr。远程清单存放在 Herdr 的状态目录中。设置 `[update] manifest_check = false` 可以禁用后台远程清单检查。 - -本地覆盖可以从平台配置目录替换远程或内置清单: - -```text -~/.config/herdr/agent-detection/<agent>.toml -``` - -本地覆盖始终优先。没有本地覆盖时,Herdr 在缓存的远程清单和运行中二进制文件内置的清单之间,选择更新且兼容的那个。在调试构建上,同一个配置助手可能使用 `herdr-dev` 之类的开发目录。无效的覆盖文件会被忽略并给出警告,Herdr 会对该智能体回退到缓存的远程或内置清单。 - -远程清单只为 Herdr 已经知道如何识别的智能体修补检测规则。添加全新的智能体仍然需要更新 Herdr 二进制文件,以获得进程检测、标签和集成行为。 - -运行中的服务器在启动时把生效的清单加载进内存。自动的远程清单更新会在写入新规则后重新加载该内存缓存。运行 `herdr server update-agent-manifests` 可以立即拉取远程清单更新并重载运行中的服务器。手动编辑本地覆盖后,重启 Herdr 或运行 `herdr server reload-agent-manifests` 把文件应用到运行中的服务器。 - -当某个窗格显示了错误状态时,用 `herdr agent explain`: - -```bash -herdr agent explain <target> -herdr agent explain --file screen.txt --agent codex --json -``` - -实时 explain 由运行中的服务器评估,因此反映的是生效的清单缓存。explain 输出包括: 智能体、最终状态、屏幕检测是否被完整生命周期权威跳过、清单来源和版本、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态、匹配的规则、可见证据标志、已评估规则的匹配器和区域证据、转写查看器的跳过更新原因,以及没有规则匹配时的 idle 回退原因。 - -Herdr 可以在 tmux 作为外层终端环境时运行。智能体检测不会检查在 Herdr 窗格内启动的 tmux 会话。如果某个 shell 框架在 Herdr 内自动进入 tmux,Herdr 看到的窗格进程就是 `tmux`,而不是它背后的智能体。 - -## 状态汇总 - -侧边栏会把状态向上汇总。 - -一个 blocked 的智能体会让它的窗格、标签页和工作区看起来是 blocked。一个 working 的智能体会让工作区看起来处于活跃状态。一个 done 的智能体在你查看之前会一直保持可见。 - -这就是 Herdr 的主要工作流: 启动多个智能体,让它们并行工作,用侧边栏看哪个项目需要决策、哪个还在运行、哪个已经可以审阅。 - -## 直接集成 - -为你使用的每个智能体安装集成;它让 Herdr 获得钩子或插件上报,而不是只靠屏幕检测: - -```bash -herdr integration install claude -herdr integration status -``` - -每个受支持的智能体都有自己的集成名称和行为。按智能体的细节和完整安装列表见[集成](/zh-cn/docs/integrations/)。 - -## 自定义智能体标签 - -你可以重命名智能体目标的显示名: - -```bash -herdr agent rename w1:p1 reviewer -herdr agent rename reviewer --clear -``` - -目标使用唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。 - -## 自定义状态标签 - -集成只把生命周期状态作为语义状态上报。展示自定义应通过窗格元数据令牌单独添加。 - -```bash -herdr pane report-agent w1:p1 \ - --source custom:indexer \ - --agent docs-bot \ - --state working - -herdr pane report-metadata w1:p1 \ - --source custom:indexer-display \ - --token summary=indexing -``` - -`state` 控制等待、通知和汇总。`summary` 令牌只影响展示,可在智能体侧边栏行中写成 `$summary`。 - -智能体侧边栏行也可以选择使用 `terminal_title` 或 `terminal_title_stripped`;两者都不在默认行中。前者显示经过安全规范化的最新 OSC 0/2 终端标题,后者会移除开头一个已识别的活动或旋转指示符字形及其后的空白。这些值由 Herdr 服务器所有,冷重启后不会保留,并且独立于元数据标题和语义智能体状态。因此,如果移除后的文本不变,旋转动画可以改变原始标题而不触发窗格更新。 - -## 直接附加到智能体 - -把当前终端附加到某一个智能体终端,而不是完整的 Herdr UI: - -```bash -herdr agent attach reviewer -``` - -用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。 - -用鼠标滚轮或普通的 page up/page down 滚动。正常输入会跳回底部。 - -如果另一个直接附加客户端已经拥有输入,用 `--takeover`: - -```bash -herdr agent attach reviewer --takeover -``` - -想对非智能体终端获得相同的直接附加行为时,用 `herdr terminal attach <terminal_id>`。 diff --git a/website/src/content/docs/zh-cn/cli-reference.mdx b/website/src/content/docs/zh-cn/cli-reference.mdx deleted file mode 100644 index 03831dc7..00000000 --- a/website/src/content/docs/zh-cn/cli-reference.mdx +++ /dev/null @@ -1,444 +0,0 @@ ---- -title: CLI 参考 -description: 用于会话、工作区、标签页、窗格、通知、智能体、等待、集成和状态的 Herdr 命令。 ---- - -Herdr 的 CLI 通过与集成和智能体相同的本地 socket API 与运行中的服务器通信。 - -大多数命令输出 JSON 响应。需要确定性自动化时,从脚本中使用它们。 - -## 启动与状态 - -```bash -herdr # 启动或连接默认会话 -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 # 对受支持的运行中服务器启用实时交接 -herdr completion zsh # 生成 zsh 补全脚本 -herdr channel show # 打印 stable 或 preview -herdr channel set preview # 启用预览构建 -herdr channel set stable # 把 Linux/macOS 直接安装切回稳定版 -herdr --version # 打印版本 -``` - -状态命令: - -```bash -herdr status -herdr status server -herdr status client -``` - -API schema 命令: - -```bash -herdr api schema -herdr api schema --json -herdr api schema --output herdr-api.schema.json -``` - -`herdr api schema` 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 `--json`;要写入文件则使用 `--output PATH`。 - -## Shell 补全 - -```bash -herdr completion zsh -herdr completions zsh -herdr completion bash -herdr completion fish -herdr completion powershell -herdr completion elvish -``` - -`completion` 会把脚本打印到 stdout。`completions` 是别名。临时 zsh 会话可以直接加载脚本: - -```bash -source <(herdr completion zsh) -``` - -持久 zsh 设置中,把生成的 `_herdr` 函数写到 `compinit` 运行前已经在 `fpath` 上的位置: - -```bash -mkdir -p ~/.zfunc -herdr completion zsh > ~/.zfunc/_herdr -``` - -然后确认 `.zshrc` 包含: - -```zsh -fpath=(~/.zfunc $fpath) -autoload -Uz compinit -compinit -``` - -## 服务器 - -```bash -herdr server -herdr server stop -herdr server reload-config -herdr server agent-manifests [--json] -herdr server update-agent-manifests [--json] -herdr server reload-agent-manifests -``` - -`herdr server` 显式运行无界面服务器,适合被监管或服务式的部署。`reload-config` 在不重启窗格的情况下应用可重载设置。`agent-manifests` 显示生效的智能体检测清单来源、缓存的远程版本和最近的远程更新结果。`update-agent-manifests` 立即拉取远程清单更新,重载到运行中的服务器,并打印更新后的清单状态;要原始状态响应就加 `--json`。`reload-agent-manifests` 在编辑本地覆盖后,把智能体检测清单重载到运行中的服务器。 - -## 通知 - -```bash -herdr notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request] -``` - -`notification show` 使用配置的 `[ui.toast]` 投递方式。`--position` 只影响 Herdr 应用内的 toast。`--sound` 默认为 `none`;`done` 和 `request` 只在通知实际显示时播放已有的完成音和需要关注音。 - -## 会话 - -```bash -herdr session list [--json] -herdr session attach <name> -herdr session stop <name> [--json] -herdr session delete <name> [--json] -``` - -需要显式停止默认会话时,把会话名写成 `default`。 - -## 工作区 - -```bash -herdr workspace list -herdr workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus] -herdr workspace get <workspace_id> -herdr workspace focus <workspace_id> -herdr workspace rename <workspace_id> <label> -herdr workspace report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N] -herdr workspace close <workspace_id> -``` - -不抢占焦点地创建工作区: - -```bash -herdr workspace create --cwd ~/project --label api --no-focus -``` - -工作区是顶层项目或工作上下文。创建工作区也会创建第一个标签页和根窗格。JSON 响应中的 `.result.workspace.workspace_id`、`.result.tab.tab_id` 和 `.result.root_pane.pane_id` 是对应 ID。 - -## Worktree - -```bash -herdr worktree list [--workspace ID | --cwd PATH] [--json] -herdr worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--json] -herdr worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--json] -herdr worktree remove --workspace ID [--force] [--json] -``` - -worktree 是带有 Git 检出来源信息的普通 Herdr 工作区。`worktree create` 创建一个 Git worktree 检出,作为工作区打开,并与父仓库工作区分到一组。如果 `--branch` 指向已有的本地分支,Herdr 检出它;否则从 `--base` 或 `HEAD` 创建分支。没有 `--path` 时,Herdr 在 `<worktrees.directory>/<repo>/<branch-slug>` 下创建检出。 - -`workspace close` 只关闭 Herdr 状态。`worktree remove` 是显式的检出删除路径;它运行 `git worktree remove`,从不删除分支,并在 Git 拒绝脏检出时要求 `--force`。 - -## 标签页 - -```bash -herdr tab list [--workspace <workspace_id>] -herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus] -herdr tab get <tab_id> -herdr tab focus <tab_id> -herdr tab rename <tab_id> <label> -herdr tab close <tab_id> -``` - -标签页是工作区内的另一个终端布局。不指定 `--workspace` 时,`tab create` 使用活动工作区;如果没有活动工作区则失败。JSON 响应中的 `.result.tab.tab_id` 和 `.result.root_pane.pane_id` 是对应 ID。 - -创建工作区、标签页和拆分窗格默认不改变焦点。`--focus` 选择新布局;`--no-focus` 显式表达默认行为。不指定 `--cwd` 时,新终端遵循 `terminal.new_cwd` 设置,默认跟随来源窗格或工作区。每个 `--env KEY=VALUE` 在新的根 shell 中添加或替换一个环境变量。 - -## 窗格 - -```bash -herdr pane list [--workspace <workspace_id>] -herdr pane current [--pane ID|--current] -herdr pane get <pane_id> -herdr pane layout [--pane ID|--current] -herdr pane process-info [--pane ID|--current] -herdr pane neighbor --direction left|right|up|down [--pane ID|--current] -herdr pane edges [--pane ID|--current] -herdr pane focus --direction left|right|up|down [--pane ID|--current] -herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current] -herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off] -herdr pane rename <pane_id> <label>|--clear -herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus] -herdr pane swap --direction left|right|up|down [--pane ID|--current] -herdr pane swap --source-pane ID --target-pane ID -herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus] -herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus] -herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus] -herdr pane close <pane_id> -``` - -接受 `--current` 的窗格命令在 Herdr 窗格内运行时使用调用方的 `HERDR_PANE_ID`。对 `pane split` 而言,显式窗格 ID 或 `--pane ID` 拆分该窗格,`--current` 拆分调用方窗格,省略目标则使用 UI 当前聚焦的窗格。拆分响应中的新窗格 ID 位于 `.result.pane.pane_id`。 - -执行 `pane move` 后,后续命令应使用 `.result.move_result.pane.pane_id`。跨工作区移动会改变带工作区前缀的窗格 ID;旧值保留在 `.result.move_result.previous_pane_id`。运行中进程的 `HERDR_PANE_ID`、`HERDR_TAB_ID` 和 `HERDR_WORKSPACE_ID` 保持启动时的值,但 Herdr 会把旧窗格 ID 保留为该终端的别名,所以使用 `--current` 的窗格命令仍能解析它。实时智能体名称也会跟随终端。 - -读取输出: - -```bash -herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw] -herdr pane read <pane_id> --source visible --ansi -herdr pane read <pane_id> --source recent-unwrapped --lines 120 -``` - -`pane read` 直接打印 UTF-8 终端文本。默认去除 ANSI 转义;来源包含样式时,使用 `--format ansi` 或 `--ansi` 保留。`detection` 来源始终是纯文本。对 recent 类来源,`--lines N` 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 `visible` 和 `detection`,省略 `--lines` 会返回完整快照,指定时保留按换行分隔的最后 N 行。`agent read` 使用相同的输出和行数行为。 - -发送输入: - -```bash -herdr pane send-text <pane_id> <text> -herdr pane send-keys <pane_id> <key> [key ...] -herdr pane run <pane_id> <command> -``` - -`<key>` 使用 Herdr 的组合键语法: `a` 这类普通可打印键,`enter`、`tab`、`esc`、`backspace`、`left`、`right`、`up`、`down` 这类特殊键,`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键,`f1` 这类功能键,以及 `minus`、`plus`、`backtick` 这类命名标点。旧式的 `C-c` 和 `c-c` 作为 `ctrl+c` 的别名被接受。 - -标准拼写是 `esc`;也接受 `escape`。 - -`pane run` 会遵循当前的 bracketed paste 模式,并把文本和 Enter 作为一个原子操作提交。发送命令时优先用它,而不是 `send-text` 加 `send-keys Enter`;单独的发送操作仍是底层操作,不会提交命令。 - -从自定义钩子上报智能体状态: - -```bash -herdr pane report-agent <pane_id> \ - --source ID \ - --agent LABEL \ - --state idle|working|blocked|unknown \ - [--message TEXT] \ - [--seq N] \ - [--agent-session-id ID] \ - [--agent-session-path PATH] - -herdr pane report-agent-session <pane_id> \ - --source ID \ - --agent LABEL \ - [--seq N] \ - [--agent-session-id ID] \ - [--agent-session-path PATH] \ - [--session-start-source SOURCE] - -herdr pane release-agent <pane_id> \ - --source ID \ - --agent LABEL \ - [--seq N] -``` - -`report-agent-session` 只更新原生会话身份,不上报生命周期状态。`release-agent` 在智能体进程退出时结束该来源的生命周期权威。 - -当官方集成上报了原生会话引用时,`pane get`、`pane list`、`agent get` 和 `agent list` 会包含一个只读的 `agent_session` 对象。没有存储原生会话引用时,该字段被省略。 - -当 Herdr 能解析控制窗格的前台进程的 cwd 时,这些命令会包含 `foreground_cwd`。已有的 `cwd` 字段仍然是用于标签和 follow-cwd 行为的窗格/工作区 cwd。 - -上报仅用于展示的窗格元数据,而不接管语义状态: - -```bash -herdr pane report-metadata <pane_id> \ - --source ID \ - [--agent LABEL] \ - [--applies-to-source ID] \ - [--title TEXT|--clear-title] \ - [--display-agent TEXT|--clear-display-agent] \ - [--state-label STATUS=TEXT] \ - [--clear-state-labels] \ - [--token NAME=VALUE] \ - [--clear-token NAME] \ - [--seq N] \ - [--ttl-ms N] -``` - -`STATUS` 是 `idle`、`working`、`blocked`、`done` 或 `unknown` 之一。`--agent` 和 `--applies-to-source` 只守卫 `--title`、`--display-agent` 和 `--state-label`,不守卫令牌补丁。上报方负责清除令牌或刷新 TTL。用 `--display-agent` 修改可见名称。 - -元数据文本在存储前会被规范化。Herdr 去掉首尾空白、移除控制字符,并把 `--title`、`--display-agent`、每个 `--state-label` 和令牌值截断到 80 个字符。规范化后为空的令牌值会清除该键。 - -`--token` 设置一个命名展示值,`--clear-token` 删除一个值。未提及的令牌保持不变。窗格令牌可在智能体侧边栏行中写成 `$name`;工作区令牌可用于空间行。TTL 分别应用于该次调用更新的每个令牌键。 - -`--source` 和 `--applies-to-source` 必须不超过 80 个字符,并且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。`--ttl-ms` 让元数据自动过期,取值必须在 `1` 到 `86400000` 毫秒之间。想让元数据一直保留到被替换、清除或窗格或工作区关闭时,省略它。`--seq` 让 Herdr 忽略来自同一 `--source` 的过期上报;过期上报会被 API 接受,但被窗格状态忽略。每个窗格或工作区在其生命周期内最多接受来自 32 个不同来源的带序号令牌上报,清除或过期不会释放这些来源名额。 - -## 智能体 - -窗格与智能体的模型和完整协调示例见[智能体自动化](/zh-cn/docs/agent-automation/)。 - -```bash -herdr agent list -herdr agent get <target> -herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] -herdr agent send-keys <target> <key> [key ...] -herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS] -herdr agent rename <target> <name>|--clear -herdr agent focus <target> -herdr agent wait <target> [--until STATUS]... [--timeout MS] -herdr agent attach <target> [--takeover] -herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>] -herdr agent explain <target> [--json|--verbose] -herdr agent explain --file PATH --agent LABEL [--json|--verbose] -``` - -智能体目标只能是唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。通过 `agent start` 启动的智能体必须有名称;手动启动的智能体保持未命名,通过窗格 ID 寻址。 - -`agent start` 会在现有可用 shell 窗格中启动智能体:交互式 shell 必须占用前台,不能有正在前台运行的命令、编辑器或智能体。拓扑必须单独创建。名称在实时智能体中必须唯一,并匹配 `[a-z][a-z0-9_-]{0,31}`。支持的 kind 是 `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`omp`、`mastracode`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli` 和 `maki`。名称属于当前窗格占用者,在该智能体退出、release 或被替换时清除;短暂的检测不确定不会清除它。 - -start 只有在预期智能体占用同一终端并可接受交互输入后才返回。默认启动超时是 30000 毫秒;显式值必须大于 3000 且不超过 300000。 - -`agent prompt` 遵循当前的 bracketed paste 模式，即使智能体处于 working 也会原子地提交文本和编码后的 Enter。使用 `--wait` 时，从非 working 状态发送的提示必须在五秒内产生可观察的生命周期变化，否则 Herdr 返回 `agent_prompt_stalled`；调用方超时不超过五秒时，仍返回普通的 `timeout` 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。`--until` 用于缩小匹配状态，不带 `--wait` 时会被拒绝。独立的 `agent wait` 在当前状态匹配时立即返回。两者默认匹配 `idle`、`done` 或 `blocked`；需要 `unknown` 时请明确使用 `--until unknown`。 - -`idle` 表示智能体在等待输入,且其标签页已在聚焦的 Herdr 界面中显示。`done` 是相同的底层 idle 状态,用于未查看的后台工作完成后。聚焦该标签页或用 `pane focus` / `agent focus` 指向它会标记为已查看;仅通过 CLI 读取不会改变它。`blocked` 表示 Herdr 识别到审批或提问界面。`unknown` 表示智能体存在但无法可靠分类,不代表工作成功。 - -`agent send-keys` 发送 `enter`、`up`、`esc`、`ctrl+c` 等逻辑按键。Herdr 会在写入任何字节前验证所有按键。`agent read` 读取解析出的终端流,`agent rename` 为已检测到的智能体命名。 - -`agent explain` 请求运行中的服务器对屏幕检测所用的同一份底部缓冲区检测快照进行分类,因此实时输出反映服务器生效的清单缓存。因为它使用 `agent.explain` socket 方法,升级 Herdr 后,请先重启或交接到更新后的服务器,再使用实时 explain。用 `--file PATH --agent LABEL` 可以改为在本地解释一份保存的样本。默认输出显示智能体、最终状态、清单来源和版本、匹配的规则及其区域证据,以及任何回退、跳过或警告原因。加 `--verbose` 可以看到可见证据标志、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态,以及带匹配器和区域证据的完整已评估规则列表。提交问题报告或写测试时加 `--json`。 - -普通终端、服务器、测试、shell 或底层终端控制,请使用 `pane send-text`、`pane send-keys`、`pane run` 和 `terminal attach`。想带回车提交命令时用 `pane run`。 - -## 直接终端附加 - -```bash -herdr terminal attach <terminal_id> [--takeover] -herdr terminal title set <title> -herdr terminal title clear -``` - -从直接附加中用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。 -`terminal title clear` 恢复 Herdr 默认的外层终端窗口标题。 - -## 输出等待 - -等待窗格中的输出: - -```bash -herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw] -``` - -普通命令和服务器用 `pane wait-output`。编程智能体用 `agent wait`。 - -`pane wait-output` 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制。`--match` 在单行中查找字面子串;`--regex` 使用 Rust 正则表达式语法并逐行匹配。 - -`pane wait-output`、`agent wait` 和 `agent prompt --wait` 在省略 `--timeout` 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。 - -## 集成 - -```bash -herdr integration install pi -herdr integration install omp -herdr integration install claude -herdr integration install codex -herdr integration install copilot -herdr integration install devin -herdr integration install droid -herdr integration install kimi -herdr integration install opencode -herdr integration install kilo -herdr integration install hermes -herdr integration install mastracode -herdr integration install qodercli -herdr integration install cursor -herdr integration uninstall pi -herdr integration uninstall omp -herdr integration uninstall claude -herdr integration uninstall codex -herdr integration uninstall copilot -herdr integration uninstall devin -herdr integration uninstall droid -herdr integration uninstall kimi -herdr integration uninstall opencode -herdr integration uninstall kilo -herdr integration uninstall hermes -herdr integration uninstall mastracode -herdr integration uninstall qodercli -herdr integration uninstall cursor -herdr integration status [--outdated-only] -``` - -## 插件 - -插件命令用于安装和运行本地可执行的工作流插件。插件是清单加进程外命令;Herdr 负责宿主侧,插件负责自己的实现语言。 - -安装、列出和移除插件: - -```bash -herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes] -herdr plugin list [--plugin ID] [--json] -herdr plugin uninstall <plugin_id|owner/repo[/subdir...]> -herdr plugin enable <plugin_id> -herdr plugin disable <plugin_id> -``` - -`plugin install` 只接受 GitHub 简写,比如 `ogulcancelik/herdr-plugin-examples/worktree-bootstrap`。它使用 `git`,在交互式终端显示信任预览,运行受支持的清单构建命令,并把 GitHub 安装保存在 Herdr 管理的目录中。非交互式安装用 `--yes`。重新安装 GitHub 管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上。插件清单必须声明 `min_herdr_version`;当插件要求更新的 Herdr 二进制时,install 和 link 会失败。`plugin list` 默认是人类可读的;要原始 API 响应就传 `--json`。 - -本地开发: - -```bash -herdr plugin link <path> [--disabled] -herdr plugin unlink <plugin_id> -``` - -`plugin link` 接受包含 `herdr-plugin.toml` 的插件目录,或直接指向清单的路径。从本地检出编写或测试插件时,它仍然是正确的命令。`plugin unlink` 注销插件、不动文件。`plugin uninstall` 注销插件,并同时删除 Herdr 管理的 GitHub 检出文件。对 GitHub 安装,uninstall 既接受插件 id,也接受与 install 相同的 `owner/repo[/subdir...]` 简写。动作、事件钩子、窗格和链接处理器在清单中声明;运行时动作注册不在 v1 范围内。 - -配置目录: - -```bash -herdr plugin config-dir <plugin_id> -``` - -`plugin config-dir` 打印插件的配置目录,需要时会创建它 (旧版插件配置位置存在时会从那里初始化)。在安装文档和 shell 脚本中用它给用户指出一个稳定路径,用于存放 `.env` 等用户可编辑配置,与托管的插件检出分开。 - -动作: - -```bash -herdr plugin action list [--plugin ID] -herdr plugin action invoke <action_id> [--plugin ID] -``` - -`plugin action invoke` 为一个已安装、已启用、平台兼容的插件动作启动清单命令,并在 JSON 响应中打印已启动命令的日志记录。当多个插件使用相同的动作 id 时,使用限定的动作 id (`plugin.id.action`)。本地动作 id 不能包含点,所以即使插件 id 包含点,限定 id 也不会有歧义。 - -日志: - -```bash -herdr plugin log list [--plugin ID] [--limit N] -``` - -托管终端窗格: - -```bash -herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus] -herdr plugin pane focus <pane_id> -herdr plugin pane close <pane_id> -``` - -`plugin pane open` 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 `[[panes]]` 命令作为 Herdr 管理的终端窗格启动。清单的默认值是 `overlay`,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页、缩放窗格,或不改变标签页布局的会话级模态 `popup` 打开。`--width` 和 `--height` 以终端单元格数或 `80%` 这样的百分比设置弹窗外层尺寸;省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗不是 Herdr 窗格,不会收到 `HERDR_PANE_ID`,也不参与 pane 或智能体 API。非终端的原生插件窗格是之后的能力面。 - -`--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 管理的变量保持权威。 - -## 读取来源 - -| 来源 | 含义 | -| --- | --- | -| `visible` | 当前渲染的屏幕。最适合 UI 反馈循环。 | -| `recent` | 带终端折行的最近回滚内容。 | -| `recent-unwrapped` | 不带软折行的最近回滚内容。最适合日志。 | -| `detection` | 智能体屏幕检测使用的底部缓冲区快照。 | - -此表描述读取时的含义。仅对 `pane wait-output` 而言,`recent` 和 `recent-unwrapped` 都搜索 recent 的未折行快照,默认写法仍是 `recent`。 - -## 环境变量 - -| 变量 | 用途 | -| --- | --- | -| `HERDR_CONFIG_PATH` | 覆盖配置文件路径。 | -| `HERDR_SESSION` | 为 CLI 命令选择命名会话。 | -| `HERDR_SOCKET_PATH` | 底层 socket 路径覆盖。 | -| `HERDR_ENV` | 在 Herdr 管理的窗格进程内设为 `1`。 | -| `HERDR_PANE_ID` | 运行中窗格进程的公开窗格 id。 | -| `HERDR_TAB_ID` | 运行中窗格进程的公开标签页 id。 | -| `HERDR_WORKSPACE_ID` | 运行中窗格进程的公开工作区 id。 | -| `HERDR_LOG` | 设置日志过滤,例如 `HERDR_LOG=herdr=debug`。 | -| `HERDR_DISABLE_SOUND` | 即使启用了声音通知也禁用声音播放。 | diff --git a/website/src/content/docs/zh-cn/concepts.mdx b/website/src/content/docs/zh-cn/concepts.mdx deleted file mode 100644 index ab950416..00000000 --- a/website/src/content/docs/zh-cn/concepts.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: 核心概念 -description: 理解 Herdr 的工作区、标签页、窗格、智能体、会话和模式。 ---- - -Herdr 是一个终端工作区管理器。它让真实的终端进程持续运行,并在其之上添加结构。 - -## 工作区 - -工作区是最顶层的项目容器。为每个仓库、任务或调查使用一个工作区。 - -工作区拥有标签页和窗格。它在侧边栏中的状态由内部的智能体汇总而来,让你一眼看出哪个项目需要关注。 - -## 标签页 - -标签页是工作区内的一种布局。用标签页来分隔不同视图,比如 `agents`、`logs`、`server` 或 `review`。 - -标签页可以通过 CLI 和 socket API 寻址。 - -## 窗格 - -窗格是一个真实的终端。Herdr 渲染终端输出,把输入传回进程,并在客户端分离后保留窗格。 - -窗格可以向右或向下分割。它们可以手动重命名、通过 CLI 读取、接收输入,以及被关闭。 - -## 鼠标 UI - -Herdr 是鼠标原生的。你可以点击窗格、标签页、工作区和智能体,可以拖动分割边框、选择文本、使用右键菜单。下文的所有操作都可以用鼠标完成;按键绑定是可选的一层。 - -如果你偏好纯键盘操作,或者不想让 Herdr 捕获鼠标输入,可以禁用鼠标捕获: - -```toml -[ui] -mouse_capture = false -``` - -## 智能体 - -智能体是 Herdr 在窗格内识别出的进程。Herdr 通过前台进程、屏幕清单和可选的集成来检测智能体。 - -智能体状态如下: - -| 状态 | 含义 | -| --- | --- | -| `blocked` | 智能体需要输入、审批或决策。 | -| `working` | 智能体正在运行。 | -| `done` | 智能体已完成,你还没有查看。 | -| `idle` | 智能体已完成或在等待,并且已被查看过。 | -| `unknown` | Herdr 无法有把握地判断状态。 | - -## 会话 - -会话是一个持久的 Herdr 服务器命名空间。默认的 `herdr` 命令连接到默认会话。 - -命名会话是彼此独立的运行时命名空间: - -```bash -herdr session list -herdr session attach work -herdr session attach side-project -``` - -优先使用工作区。当你需要完全独立的窗格、socket 和持久化运行时状态时,才使用命名会话。 - -## 客户端与服务器 - -默认情况下,Herdr 以一个后台服务器加一个或多个已连接客户端的方式运行。 - -服务器拥有窗格和进程状态。客户端是连接到该服务器的终端 UI。 - -用 `ctrl+b q` 分离客户端。服务器和智能体会继续运行。 - -如果想结束会话并停止其中的窗格,停止服务器: - -```bash -herdr server stop -``` - -## 模式 - -Herdr 有终端模式、前缀模式和导航模式。 - -终端模式把按键发送给聚焦的窗格。前缀模式在按下前缀键后等待一个 Herdr 动作。导航模式是常驻的工作区导航界面。 - -按下前缀键 (默认 `ctrl+b`),再按一个动作键,比如 `c` 新建标签页,`w` 打开工作区导航。第一次接触前缀键的概念?参见[键盘](/zh-cn/docs/keyboard/)。 diff --git a/website/src/content/docs/zh-cn/config-reference.mdx b/website/src/content/docs/zh-cn/config-reference.mdx deleted file mode 100644 index 7f70afa2..00000000 --- a/website/src/content/docs/zh-cn/config-reference.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 配置参考 -description: Herdr 的所有规范 config.toml 键，包含类型、默认值与允许的取值。 ---- - -import ConfigReference from '../../../components/ConfigReference.astro'; - -Herdr 从 `config.toml` 读取的所有规范键都在这里平铺列出，并支持筛选。 -配置的分步指南与各选项的背景说明见[配置](/zh-cn/docs/configuration/)。 - -随时可以打印带注释的完整默认配置: - -```bash -herdr --default-config -``` - -自定义命令绑定（`[[keys.command]]`）是用户自定义的表，因此不在此处逐键列出， -见[自定义命令按键绑定](/zh-cn/docs/configuration/#自定义命令按键绑定)。 - -各键的描述目前为英文。 - -<ConfigReference - placeholder="筛选键（例如 sidebar、prefix、sound…）" - noMatches="没有匹配的键。" - keyCountLabel="个键" -/> diff --git a/website/src/content/docs/zh-cn/configuration.mdx b/website/src/content/docs/zh-cn/configuration.mdx deleted file mode 100644 index bb04da07..00000000 --- a/website/src/content/docs/zh-cn/configuration.mdx +++ /dev/null @@ -1,462 +0,0 @@ ---- -title: 配置 -description: 配置 Herdr 的按键绑定、主题、侧边栏行为、通知和高级选项。 ---- - -Herdr 无需配置文件即可使用。当你想自定义按键、主题、侧边栏布局、通知或高级行为时，再添加配置文件。 - -在查找某项设置或按键绑定？请在[配置参考](/docs/config-reference/)中搜索，其中列出了每个键、类型、默认值和允许值。本页重点介绍设置方法、常用配置方案，以及需要比参考表格更详细说明的配置结构。 - -## 配置文件 - -Herdr 从以下位置读取配置： - -```text -Linux and macOS: ~/.config/herdr/config.toml -Windows: %APPDATA%\herdr\config.toml -``` - -运行 `herdr --help` 可查看系统解析后的配置路径。 - -打印完整的默认配置： - -```bash -herdr --default-config -``` - -如果想从完整配置开始，可以将其保存为你的配置文件： - -```bash -herdr --default-config > ~/.config/herdr/config.toml -``` - -如果配置值无效，Herdr 会回退到安全的默认值，并显示启动警告。 - -当 `onboarding` 缺失或为 true 时，Herdr 会显示首次运行设置。继续完成引导会写入 `onboarding = false`，并打开设置中的集成标签页。完成设置后，如果想跳过此流程，请设置该值。 - -```toml -onboarding = false -``` - -## 重载配置 - -编辑 `config.toml` 后，重载正在运行的服务器： - -```bash -herdr server reload-config -``` - -你也可以打开 Herdr 的全局菜单并选择 `reload config`。 - -重载会在不重启窗格的情况下应用大多数 UI 设置。仅启动时生效的设置仍需重启。 - -## 终端默认值 - -设置 Herdr 创建新交互式窗格时使用的可执行文件： - -```toml -[terminal] -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 如何启动新建交互式窗格的 shell： - -```toml -[terminal] -shell_mode = "auto" -``` - -`shell_mode = "auto"` 会在 macOS 上启动登录 shell，让 `/usr/libexec/path_helper` 等仅登录时生效的 PATH 设置和 Homebrew shell 初始化在新窗格中运行。在其他平台上，它会保持现有的非登录 shell 行为。使用 `"login"` 强制以登录 shell 启动，或使用 `"non_login"` 禁用登录 shell。命令窗格、分离式自定义命令按键绑定和显式 argv 启动仍使用现有的命令执行路径。 - -设置新窗格、标签页和工作区的工作目录策略： - -```toml -[terminal] -new_cwd = "follow" -``` - -`new_cwd = "follow"` 保持默认行为，并继承来源窗格或工作区。没有来源工作区时，Herdr 从 `$HOME` 启动。使用 `"home"` 可始终从 `$HOME` 启动，使用 `"current"` 可采用 Herdr 的进程目录，也可以指定 `"~/Projects"` 这样的固定路径。CLI 或 socket API 显式提供的 `--cwd` 值仍然优先。 - -## Worktree - -设置 Herdr 从侧边栏创建 Git worktree 检出时使用的根目录： - -```toml -[worktrees] -directory = "~/.herdr/worktrees" -``` - -Herdr 会在 `<directory>/<repo>/<branch-slug>` 下创建检出。若要使用同级目录风格的检出，请将其设置为 `~/Projects/herdr-worktrees` 这样的目录。应用配置时，相对路径会解析为绝对路径。 - -Git 工作区行提供 worktree 操作。`New worktree` 会创建检出：如果输入的分支已存在，则检出该本地分支，否则创建该分支；随后将其作为新的 Herdr 工作区打开，并归组到来源工作区下。`Open worktree...` 会列出该仓库现有的 Git worktree 检出；选择已打开的检出会聚焦它，选择尚未打开的检出会在同一组中打开它。 - -归组的 worktree 仍像普通 Herdr 工作区一样工作：可以聚焦、重命名和关闭，也可以拥有自己的标签页和窗格。父行是原始工作区。关闭父行会关闭整个 Herdr 组，但不会删除检出目录或分支。 - -删除 worktree 检出需要显式操作。在归组的子工作区上使用 `Delete worktree checkout...` 来运行 `git worktree remove`。Herdr 会先请求 Git 安全删除。如果 Git 因检出中存在已修改或未跟踪的文件而拒绝，Herdr 会在强制删除前再次确认。分支不会被删除。 - -## 远程连接 - -远程连接默认使用临时保活设置和连接复用兜底来管理 SSH 连接。 - -```toml -[remote] -manage_ssh_config = true -``` - -启用后，`herdr --remote` 会写入一份私有的临时 SSH 配置：先包含你的 `~/.ssh/config` 和 `/etc/ssh/ssh_config`，再添加兜底的 `ServerAliveInterval` 和 `ServerAliveCountMax` 值。你自己的保活设置优先。Herdr 还会为每次远程连接使用私有的 OpenSSH control socket，以复用首次通过身份验证的连接。设置 `manage_ssh_config = false` 可通过普通 `ssh` 进行远程连接，不使用 Herdr 生成的配置或 control socket。 - -## 按键绑定 - -有关前缀键的引导式介绍和经过验证的免前缀配置，请参阅[键盘](/docs/keyboard/)。 - -Herdr 提供类似 tmux 的前缀模式。默认前缀是 `ctrl+b`。按键绑定字符串是显式的：`prefix+n` 表示先按配置的前缀，再按 `n`；`ctrl+alt+n` 则是终端模式下的直接快捷键。 - -一个简短的按键绑定覆盖如下： - -```toml -[keys] -prefix = "ctrl+b" -goto = "prefix+g" -new_tab = "prefix+c" -next_tab = "prefix+n" -previous_tab = "prefix+p" -focus_pane_left = "prefix+h" -navigate_workspace_down = "j" -navigate_pane_down = "ctrl+j" -split_horizontal = "prefix+minus" -``` - -默认键位以前缀为主，因此 Herdr 不会抢占 shell、编辑器、tmux 或终端应用的输入。在[配置参考](/docs/config-reference/)中搜索 `keys.` 可查看每个动作及其默认绑定。应用内帮助面板可通过 `prefix+?` 打开，其中会显示当前生效的绑定。 - -当一个动作需要多个快捷键时，绑定也可以是数组： - -```toml -[keys] -next_tab = ["prefix+n", "ctrl+alt+]"] -``` - -可选动作默认不设置。使用 `prefix+` 可获得前缀模式行为；当你确实需要直接快捷键时，请使用显式的修饰组合键。 - -按键字符串支持普通按键、`ctrl+a`、`shift+n`、`alt+1`、`cmd+k` 等修饰组合键，以及 `enter`、`tab`、`esc`、`left`、`right`、`up`、`down` 等特殊键。也支持 `minus`、`comma`、`ampersand`、`plus`、`backtick` 等命名标点。直接绑定 `n` 这样的普通可打印键并不安全，因为它会拦截输入；除非你有意设置直接绑定，否则请使用 `prefix+n`。`navigate_workspace_*` 和 `navigate_pane_*` 字段仅在导航模式中生效，可以使用 `j` 或 `k` 等普通按键；它们不得使用 `prefix+`、`esc`、`enter`、`tab`、`shift+tab`、`left`、`right`，也不得使用无修饰键的 `1` 到 `9`。左右方向键是向左和向右导航窗格的永久别名。这些导航模式快捷键独立于 `focus_pane_down = "prefix+j"` 等通用动作绑定；两者使用同一按键时，打开导航模式后，导航模式快捷键优先。Alt、Cmd/Super 以及带修饰键的标点取决于你的终端和 tmux 设置。 - -如果你已有旧的自定义按键绑定，并想使用新的默认值，请运行 `herdr config reset-keys`。Herdr 会备份 `config.toml`，移除 `[keys]` 和 `[[keys.command]]`，并在重启或执行 `herdr server reload-config` 后使用内置的 v2 默认值。 - -## 索引跳转 - -索引式按键绑定在普通按键绑定字段中使用 `1..9`： - -```toml -[keys] -switch_tab = "prefix+1..9" -switch_workspace = "prefix+shift+1..9" -focus_agent = "prefix+alt+1..9" -``` - -旧版 `[keys.indexed]` 表仍会出于兼容性而解析，但新配置应优先使用显式的动作字段。 - -## 自定义命令按键绑定 - -自定义命令使用相同的按键绑定语法。 - -```toml -[[keys.command]] -key = "prefix+alt+g" -type = "popup" -command = "lazygit" -description = "run lazygit" -width = "80%" -height = "80%" -``` - -`type = "popup"` 会打开一个会话级模态弹窗,而不改变标签页布局。 -弹窗会接收包括 Escape 在内的所有终端输入,直到命令退出。 -`width` 和 `height` 是可选的;省略时默认为终端大小的一半,数字表示终端单元格数,`"80%"` 这样的字符串表示终端区域的百分比。 -尺寸包含弹窗边框,过小的值会限制为弹窗最小尺寸。 -弹窗命令不会收到 `HERDR_PANE_ID`;可使用 `HERDR_ACTIVE_PANE_ID` 引用底层平铺窗格。 - -在 Unix 和 macOS 上,还可以打开一个临时终端,而无需添加分割或标签页: - -```toml -[[keys.command]] -key = "prefix+t" -type = "popup" -command = "exec \"${SHELL:-sh}\"" -description = "open scratch terminal" -width = "80%" -height = "80%" -``` - -在 Windows 上,请改用 `command = "powershell.exe -NoLogo"` 之类的 shell 命令。 -退出 shell 即可关闭弹窗并恢复平铺终端视图。 - -`type = "pane"` 会打开一个临时窗格，并在命令退出时关闭它。 - -`type = "shell"` 会在后台分离运行。 - -`type = "plugin_action"` 会调用已安装插件的动作 id。当动作 id 并非全局唯一时，请使用限定 id： - -```toml -[[keys.command]] -key = "prefix+l" -type = "plugin_action" -command = "example.layout.apply" -description = "apply layout" -``` - -可以提供可选的 `description`。指定后，该描述会在按键绑定帮助面板（通过 `prefix+?` 打开）中显示，替代默认的 `'custom command'` 标签。 - -在相应值可用时，自定义命令会收到 `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ACTIVE_WORKSPACE_ID`、`HERDR_ACTIVE_TAB_ID`、`HERDR_ACTIVE_PANE_ID` 和 `HERDR_ACTIVE_PANE_CWD`。当 Herdr 能检测到聚焦窗格的工作目录时，shell 命令会从该目录运行。 - -在 Windows 上，自定义命令字符串使用 `cmd.exe /d /c`，因此环境变量应采用 `%HERDR_BIN_PATH%` 语法。若要运行 PowerShell 语法，请显式调用它，例如 `powershell.exe -NoProfile -Command "..."`。 - -## 主题 - -选择内置主题： - -```toml -[theme] -name = "catppuccin" -``` - -在[配置参考](/docs/config-reference/)中搜索 `theme.name` 可查看所有内置主题。如果想让 Herdr UI 颜色跟随宿主终端的 ANSI 调色板，请使用 `terminal`。 - -要让 Herdr 在宿主终端报告明暗外观变化时自动切换自身的 UI 主题，请启用主题自动切换： - -```toml -[theme] -name = "catppuccin" -auto_switch = true -light_name = "catppuccin-latte" -dark_name = "catppuccin" -``` - -`auto_switch` 默认为 `false`，因此现有主题配置会保持手动行为。如果省略 `light_name` 或 `dark_name`，且配置的 `name` 存在对应的内置姊妹主题，Herdr 会使用该主题，例如 `tokyo-night`/`tokyo-night-day` 或 `gruvbox`/`gruvbox-light`。在设置中手动选择主题会禁用 `auto_switch`。 - -你可以覆盖单个颜色： - -```toml -[theme.custom] -panel_bg = "reset" -accent = "#a6e3a1" -green = "#a6e3a1" -blue = "#89b4fa" -red = "#f38ba8" -yellow = "#f9e2af" -``` - -颜色值支持十六进制、命名颜色、`rgb(r,g,b)`，以及 `reset`、`default`、`none`、`transparent` 等重置别名。 - -## UI 与侧边栏 - -侧边栏是 Herdr 的主仪表盘。在[配置参考](/docs/config-reference/)中搜索 `ui.`，可查看尺寸、折叠模式、Agent 面板排序、鼠标行为、窗格边框和其他显示设置。 - -### 侧边栏行布局 - -展开的桌面侧边栏会将 `rows` 中的每个内层数组渲染为一行。以下是完整的默认布局： - -```toml -[ui.sidebar.agents] -row_gap = 0 -rows = [ - ["state_icon", "workspace", "tab"], - ["agent"], -] - -[ui.sidebar.spaces] -row_gap = 0 -rows = [ - ["state_icon", "workspace"], - ["branch", "git_status"], -] -``` - -Agent 行支持以下内置 token： - -- `state_icon` — 智能体语义状态的彩色图标。 -- `state_text` — `idle`、`working`、`blocked`、`done` 或 `unknown`；如果报告中包含显示标签，也会一并显示。 -- `workspace` — 工作区名称。 -- `tab` — 标签页名称（如有）。 -- `pane` — 窗格名称（如有）。 -- `agent` — 检测到或报告的智能体显示名称。 -- `terminal_title` — 经过安全规范化的最新 OSC 0/2 终端标题。 -- `terminal_title_stripped` — 从终端标题开头移除一个可识别的活动或旋转指示符字形及其后空白后的结果。 -- `$name` — 名为 `name` 的自定义窗格元数据。 - -Space 行支持以下内置 token： - -- `state_icon` — Space 汇总后智能体状态的彩色图标。 -- `state_text` — Space 汇总后智能体状态的文本。 -- `workspace` — 工作区名称。 -- `branch` — Git 分支（如有）。 -- `git_status` — 非零时显示 Git ahead 和 behind 数量。 -- `$name` — 名为 `name` 的自定义工作区元数据。 - -token 会按配置顺序渲染。Herdr 通常使用 ` · ` 分隔相邻值，并在 `state_icon` 后使用一个空格。缺失值及其分隔符会消失；当一行中的所有 token 都没有值时，该行会消失。每个布局最多可包含 16 行，每行最多可包含 16 个 token。 - -也可以用内联样式表定义 token： - -```toml -[ui.sidebar.agents] -rows = [ - ["state_icon", { token = "workspace", bold = false }, "tab"], - [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }], -] -``` - -`fg` 只接受严格的 `#RGB` 或 `#RRGGBB`，`bold` 和 `dim` 接受布尔值。省略字段会保留上下文样式；显式 `false` 会移除对应修饰。样式只作用于当前出现位置。为 `git_status` 设置 `fg` 后，ahead 和 behind 会使用同一种颜色，而不是默认的绿色和红色。token 样式不会改变分隔符或行背景。 - -`row_gap` 分别控制 Agent 和 Space 面板中条目之间的空白终端行数。默认值为 `0`，会紧密排列条目；设为 `1` 可恢复之前的间距。它不会在 `rows` 声明的内容行之间添加间距。连续缩进的 worktree 子项仍会作为一个 Space 组紧密排列。 - -在 `rows_by_agent` 下为已知智能体覆盖完整的 Agent 布局： - -```toml -[ui.sidebar.agents] -rows = [ - ["state_icon", "agent", "state_text"], - ["workspace", "tab"], -] - -[ui.sidebar.agents.rows_by_agent] -claude = [ - ["state_icon", "agent", "state_text"], - ["terminal_title_stripped"], - ["workspace", "tab"], -] -``` - -覆盖项会替换 `rows`，而不是扩展它。覆盖项的键是区分大小写的规范智能体 ID，例如 `claude`、`codex` 和 `pi`。不接受 `claude-code` 等检测别名。没有覆盖项的智能体（包括自定义报告的智能体）会使用 `rows`。 - -自定义 `$name` token 是动态值，而不是字面文本。先将 token 添加到布局，再通过脚本或插件报告其值： - -```toml -[ui.sidebar.agents] -rows = [ - ["state_icon", "agent", "$model"], - ["$summary"], - ["workspace", "tab"], -] -``` - -```bash -herdr pane report-metadata <pane_id> \ - --source my-agent-hook \ - --token model=opus \ - --token summary="reviewing authentication" -``` - -自定义 Space token 可用同样的方式通过 `herdr workspace report-metadata` 报告。未报告的自定义 token 会直接消失。 - -元数据上报方只提供值；样式由本地侧边栏配置控制。有关限制、清除、顺序和过期值的信息，请参阅 [CLI 参考：报告元数据](/docs/cli-reference/#panes)。 - -侧边栏行设置仅影响展开的桌面侧边栏。折叠视图和移动视图仍使用紧凑布局。 - -## 通知 - -当后台智能体完成任务或需要输入时，Herdr 可以通知你： - -```toml -[ui.toast] -delivery = "herdr" -delay_seconds = 1 - -[ui.toast.herdr] -position = "bottom-right" -``` - -选择 `herdr` 可使用应用内 toast，选择 `terminal` 可使用适合 SSH 场景的外层终端通知，选择 `system` 可使用本地操作系统通知服务，选择 `off` 可禁用弹出通知。Herdr 会抑制活动标签页的弹出通知。在[配置参考](/docs/config-reference/)中搜索 `ui.toast`，可查看位置、延迟行为和剪贴板反馈设置。 - -## 声音 - -声音通知通过本地 Herdr 客户端播放。自定义声音必须是 mp3 文件；相对路径从配置文件所在目录解析。 - -```toml -[ui.sound] -path = "sounds/notification.mp3" -done_path = "sounds/done.mp3" -request_path = "sounds/request.mp3" -``` - -`path` 为所有声音通知设置同一种声音。`done_path` 和 `request_path` 只覆盖完成和需要输入时的声音。 - -按智能体覆盖声音设置时，可使用 `default`、`on` 或 `off`。键应使用检测到的智能体标签，例如 `claude`、`codex`、`devin` 或 `droid`。Droid 默认静音。 - -```toml -[ui.sound.agents] -droid = "off" -claude = "on" -``` - -## 高级配置 - -在[配置参考](/docs/config-reference/)中搜索回滚缓冲区限制、嵌套启动以及其他高级或实验性设置。启用窗格屏幕历史前，请参阅[会话状态与恢复](/docs/session-state/)；该指南说明了保存窗格内容带来的安全取舍。 - -## Kitty graphics - -面向已连接本地客户端的 Kitty graphics 渲染是一项实验性功能，默认禁用： - -```toml -[experimental] -kitty_graphics = true -``` - -仅在测试终端图像行为时启用。 - -## 智能体会话恢复 - -默认情况下，Herdr 会在服务器重启后恢复受支持的智能体对话： - -```toml -[session] -resume_agents_on_restore = true -``` - -只有通过官方集成获得有效原生会话引用的窗格才能恢复；其他窗格会作为普通 shell 恢复。有关受支持的智能体和持久化行为，请参阅[会话状态与恢复](/docs/session-state/)。 - -## IME 光标跟踪 - -在 macOS 上，隐藏硬件光标的 AI 智能体 TUI 可能导致原生输入法候选窗口无法跟随聚焦窗格。使用以下设置可为这些窗格显示光标锚点： - -```toml -[experimental] -reveal_hidden_cursor_for_cjk_ime = true -cjk_ime_agents = ["claude", "pi", "codex"] -``` - -限制 `cjk_ime_agents` 可以避免在无关应用中额外显示硬件光标。在[配置参考](/docs/config-reference/)中搜索这些键，可查看接受的智能体名称和光标形状。 - -## 前缀输入源切换 - -在 macOS 上，当前缀命令和由前缀启动的模式处于活动状态时，Herdr 可以临时切换到系统中支持 ASCII 的输入源： - -```toml -[experimental] -switch_ascii_input_source_in_prefix = true -``` - -返回终端输入或进入文本字段时，Herdr 会恢复之前的输入源。此设置在其他平台上无效。 - -## 环境变量 - -| 变量 | 用途 | -| --- | --- | -| `HERDR_CONFIG_PATH` | 覆盖配置文件路径。 | -| `HERDR_SESSION` | 为 CLI 命令选择命名会话。 | -| `HERDR_SOCKET_PATH` | 覆盖底层 socket 路径。 | -| `HERDR_LOG` | 设置日志过滤，例如 `HERDR_LOG=herdr=debug`。 | -| `HERDR_DISABLE_SOUND` | 即使 `[ui.sound] enabled = true` 也禁用声音播放。 | - -## 日志 - -日志有助于诊断启动警告、集成状态或 socket API 行为。 - -常见日志文件： - -```text -~/.config/herdr/herdr.log -~/.config/herdr/herdr-client.log -~/.config/herdr/herdr-server.log -``` - -日志会自动轮转。报告问题时，请附上当前日志和轮转后的同级日志文件。 diff --git a/website/src/content/docs/zh-cn/how-to-work.mdx b/website/src/content/docs/zh-cn/how-to-work.mdx deleted file mode 100644 index 0df1b87f..00000000 --- a/website/src/content/docs/zh-cn/how-to-work.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: 使用 Herdr 的工作方式 -description: 在本地、SSH 内或通过远程连接运行 Herdr。 ---- - -在工作所在的地方运行 Herdr,从你所在的任何地方连接。 - -Herdr 由一个后台会话服务器和一个或多个终端客户端组成。窗格在服务器中持续运行。客户端负责连接、分离和渲染会话。 - -## 本地工作 - -在项目目录中启动 Herdr: - -```bash -herdr -``` - -Herdr 会自动启动或连接到本地后台会话。你不需要管理 socket。在窗格里照常运行 shell、服务器、测试和智能体。 - -用 `ctrl+b q` 分离客户端。窗格会继续运行。 - -之后重新连接: - -```bash -herdr -``` - -如果想结束会话并停止其中的窗格,停止服务器: - -```bash -herdr server stop -``` - -## 通过普通 SSH 的远程工作 - -SSH 到有代码和凭据的机器,然后在那里运行 Herdr: - -```bash -ssh you@server -herdr -``` - -这和终端复用器的用法一样。你的 shell 在远程,Herdr 服务器在远程,智能体和窗格都运行在远程机器上。用 `ctrl+b q` 分离并断开连接,之后再 SSH 回去,重新运行 `herdr`。 - -当你本来就工作在 SSH shell 里、在手机或平板的 SSH 客户端上,或者想要最简单的配置时,用这条路径。 - -## 用手机工作 - -你不需要 Herdr 手机应用或 Web 仪表盘。在手机上装任意一个 SSH 客户端,连到智能体所在的机器,在那里启动 Herdr: - -```bash -ssh you@server -herdr -``` - -同一个持久的 Herdr 会话就会在手机终端中打开。TUI 会适应窄屏,所以你可以在不离开 SSH 的情况下检查智能体、切换工作区、查看窗格。 - -在 iPhone 上,[moshi](https://getmoshi.app/) 这类应用表现很好。 - -<div class="mobile-doc-shots"> - <figure> - <img src="/assets/mobile-agent-session-v2.jpeg" alt="手机上通过 SSH 的 Herdr 智能体会话" loading="lazy" /> - <figcaption>SSH 上的智能体会话</figcaption> - </figure> - <figure> - <img src="/assets/mobile-switch-menu-v2.jpeg" alt="手机上 Herdr 的响应式切换菜单" loading="lazy" /> - <figcaption>响应式切换菜单</figcaption> - </figure> -</div> - -## 从本地终端远程工作 - -不先打开 shell,直接通过 SSH 连接: - -```bash -herdr --remote workbox -herdr --remote ssh://you@server:2222 -``` - -你本地的 Herdr 充当瘦客户端。它通过 SSH 连接,启动或连接远程 Herdr 服务器,并把 UI 流式传回你的本地终端。 - -想让远程会话用起来像本地时,用这条路径。客户端运行在你的机器上,所以图像剪贴板粘贴等本地桌面功能可以桥接到远程服务器。如果你先 SSH 再在服务器上运行 `herdr`,Herdr 就完全运行在那台服务器上,无法读取你本地桌面的剪贴板。 - -对于经常连接的目标,把主机写进 SSH 配置: - -```text -Host workbox - HostName server.example.com - User you - Port 2222 -``` - -然后这样连接: - -```bash -herdr --remote workbox -``` - -## 该用哪条路径 - -本地工作用 `herdr`。想让 Herdr 在远程 shell 上表现得像 tmux,或者在用手机 SSH 客户端时,用 `ssh you@server` 再 `herdr`。想要一个连接远程会话的本地瘦客户端 (包括本地剪贴板图像粘贴桥接) 时,用 `herdr --remote <host>`。 - -关于远程引导细节、命名远程会话、自定义二进制、直接终端附加和 `--no-session`,参见[持久化与远程访问](/zh-cn/docs/persistence-remote/)。 diff --git a/website/src/content/docs/zh-cn/index.mdx b/website/src/content/docs/zh-cn/index.mdx deleted file mode 100644 index b62a2b02..00000000 --- a/website/src/content/docs/zh-cn/index.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Herdr 文档 -description: 面向 AI 编程智能体的终端工作区管理器。 -template: splash -hero: - tagline: "安装、学习和配置 Herdr。从适合你的路径开始 — 无需任何终端复用器经验。" - image: - file: ../../../../public/assets/logo.svg - actions: - - text: 安装 Herdr - link: /zh-cn/docs/install/ - - text: 快速开始 - link: /zh-cn/docs/quick-start/ - variant: secondary ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -## 选择你的路径 - -<CardGrid> - <Card title="第一次接触终端复用器?"> - 上手不需要学习快捷键。Herdr 以鼠标为先: 点击窗格、拖动边框、通过右键菜单分割和切换。 - - [快速开始 →](/zh-cn/docs/quick-start/) - </Card> - <Card title="从 tmux 或 zellij 迁移过来?"> - 这套模型你已经很熟悉了。前缀键是 `ctrl+b`,窗格会持久保留,分离和重新连接的行为都符合你的预期。 - - [核心概念 →](/zh-cn/docs/concepts/) · [按键绑定 →](/zh-cn/docs/configuration/#按键绑定) - </Card> -</CardGrid> - -## 或者让你的智能体来介绍 - -已经在用 AI 编程智能体?让它来帮你完成入门。粘贴这个提示词: - -```text -Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step. -``` - -这份指南会教你的智能体 Herdr 的概念、安装、配置和常见问题的修复方法,让它的回答保持准确,而不是即兴发挥。 - -## 核心指南 - -<CardGrid> - <Card title="智能体"> - 了解受支持的智能体、检测行为、集成、自定义标签和直接附加。 - - [理解智能体 →](/zh-cn/docs/agents/) - </Card> - <Card title="会话状态"> - 理解分离、重启恢复、窗格历史回放、智能体原生会话恢复和实时交接。 - - [对比状态路径 →](/zh-cn/docs/session-state/) - </Card> - <Card title="配置"> - 配置按键绑定、主题、侧边栏行为、通知、回滚缓冲和高级选项。 - - [配置 Herdr →](/zh-cn/docs/configuration/) - </Card> - <Card title="API"> - 通过 CLI 和本地 socket API,从脚本、工具和智能体控制 Herdr。 - - [阅读 API 指南 →](/zh-cn/docs/socket-api/) - </Card> - <Card title="插件"> - 编写本地可执行的工作流插件,带有清单声明的动作和事件钩子。 - - [编写插件 →](/zh-cn/docs/plugins/) - </Card> - <Card title="插件市场"> - 现在就可以从 GitHub 分享插件,为仓库打上主题标签,插件市场上线时即可收录。 - - [发布插件 →](/zh-cn/docs/marketplace/) - </Card> -</CardGrid> diff --git a/website/src/content/docs/zh-cn/install.mdx b/website/src/content/docs/zh-cn/install.mdx deleted file mode 100644 index ccab07d6..00000000 --- a/website/src/content/docs/zh-cn/install.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: 安装 Herdr -description: 在 Linux、macOS 和 Windows 测试版上安装、更新和验证 Herdr。 ---- - -Herdr 为 Linux 和 macOS 提供稳定版二进制文件。Windows 原生支持是仅限预览版的测试版。 - -## 安装 - -在 Linux 或 macOS 上运行: - -```bash -curl -fsSL https://herdr.dev/install.sh | sh -``` - -在 Windows 预览测试版上,安装预览通道: - -```powershell -powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" -``` - -安装器会下载适合你平台的发布二进制文件并放到 PATH 上。在 Windows 上,Herdr 默认使用预览通道,且不会修改你的配置。安装器使用带版本号的安装文件夹,并更新一个 `current` 联接点,因此更新时不需要覆盖正在运行的 `herdr.exe`。 - -## 用 Homebrew 安装 - -如果你已经在用 Homebrew: - -```bash -brew install herdr -``` - -## 用 mise 安装 - -如果你已经在用 mise: - -```bash -mise use -g herdr -``` - -如果 mise 报 `herdr not found in mise tool registry`,请更新 mise 后重试。旧版 mise 早于 Herdr 的注册表条目;`mise use -g github:herdrdev/herdr` 可以作为临时兜底。 - -## 用 Nix 安装 - -如果你已经在用 Nix,Herdr 提供了一个从源码构建的 flake: - -```bash -nix run github:herdrdev/herdr/v0.x.y -nix build github:herdrdev/herdr/v0.x.y -nix profile install github:herdrdev/herdr/v0.x.y -``` - -把 `v0.x.y` 替换为最新的发布标签。省略标签可以跟踪 `master`,但常规安装建议使用发布标签。 - -flake 还提供一个开发 shell: - -```bash -nix develop github:herdrdev/herdr -``` - -更新时使用你安装 Herdr 的同一套 Nix 工作流。对于 profile 安装,列出 profile 条目并升级 Herdr 条目: - -```bash -nix profile list -nix profile upgrade <index-or-name> -``` - -如果 Herdr 是你自己 flake 的一个 input,更新该 input 并重建你的系统、Home Manager 或开发环境: - -```bash -nix flake update herdr -``` - -## 手动下载 - -也可以从 [GitHub releases](https://github.com/herdrdev/herdr/releases) 下载二进制文件。 - -选择匹配你系统的产物: - -| 系统 | 产物 | -| --- | --- | -| Linux x86_64 | `herdr-linux-x86_64` | -| Linux aarch64 | `herdr-linux-aarch64` | -| macOS Intel | `herdr-macos-x86_64` | -| macOS Apple silicon | `herdr-macos-aarch64` | - -在 Linux 或 macOS 上,赋予可执行权限并移动到 PATH 上的某个位置。 - -```bash -chmod +x herdr-linux-x86_64 -mv herdr-linux-x86_64 ~/.local/bin/herdr -``` - -### Windows 测试版下载 - -在 Windows 原生支持处于测试阶段期间,Windows 二进制文件只在预览版发布中提供。常规测试请使用上面的预览安装器,或从预览的 GitHub 预发布中下载 Windows 产物: - -| 系统 | 产物 | -| --- | --- | -| Windows x86_64 测试版 | `herdr-windows-x86_64.exe` | - -## 验证 - -启动 Herdr: - -```bash -herdr -``` - -如果 shell 找不到 `herdr`,重启终端,或检查安装目录是否在 PATH 上。 - -## 更新 - -Herdr 会检查新版本并在应用内通知你。也可以手动更新: - -```bash -herdr update -``` - -`herdr update` 适用于由 Herdr 自带安装器管理的安装。Homebrew、mise 和 Nix 安装请改用那些包管理器更新。 - -在 Linux 和 macOS 上,Herdr 默认使用稳定更新通道。要启用来自 `master` 的预览构建,设置通道: - -```bash -herdr channel set preview -``` - -用同样的方式把 Linux 和 macOS 的直接安装切回稳定版: - -```bash -herdr channel set stable -``` - -对于直接安装,切换通道时也会检查该通道并安装其最新二进制文件。如果该更新失败,运行 `herdr update` 从配置的通道重试。 - -预览构建是从当前开发分支手动发布的 GitHub 预发布。当你想在下一个稳定版之前拿到修复时很有用,但它们可能出现回归。Homebrew、mise 和 Nix 安装不使用预览通道。 - -Windows 测试版构建目前仅限预览通道。在稳定的 Windows 发布可用之前,Windows 上的 `herdr channel set stable` 会被拒绝。 - -默认情况下,`herdr update` 安装新二进制文件,并不打扰兼容的运行中会话。如果某次更新改变了 Herdr 的客户端/服务器协议,Herdr 会在安装后询问是否停止旧服务器。要使用新版本,请停止旧服务器。停止会退出窗格进程。对于默认会话,运行 `herdr server stop`,再运行 `herdr`。对于命名会话,运行 `herdr session stop <name>`,再运行 `herdr session attach <name>`。 - -要对受支持的运行中会话启用实验性的实时服务器交接,运行: - -```bash -herdr update --handoff -``` - -实时交接不适用于 Homebrew、mise 或 Nix 的包管理器更新。这些安装先用包管理器更新,然后在准备好使用新服务器时重启那个 Herdr 会话。如果运行中的会话仍在使用旧服务器,用 `herdr server stop` 或 `herdr session stop <name>` 停止它,再重新运行 Herdr。 - -## 系统要求 - -Herdr 稳定版支持 Linux 和 macOS。Windows 原生构建是仅限预览版的测试版发布;受支持的工作流和已知限制见 [Windows 测试版](/zh-cn/docs/windows-beta/)。 diff --git a/website/src/content/docs/zh-cn/integrations.mdx b/website/src/content/docs/zh-cn/integrations.mdx deleted file mode 100644 index c49f61db..00000000 --- a/website/src/content/docs/zh-cn/integrations.mdx +++ /dev/null @@ -1,299 +0,0 @@ ---- -title: 集成 -description: 为 Pi、OMP、Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、Qoder CLI、Cursor Agent CLI 和 MastraCode 安装 Herdr 集成。 ---- - -Herdr 自动检测受支持的智能体。官方集成可以额外提供用于恢复的原生会话身份、生命周期状态上报,或两者兼有。 - -当你想要 Claude Code/Codex/Copilot/Devin 式钩子的智能体原生会话恢复、Pi/OMP/Kimi/OpenCode/Kilo/Hermes/MastraCode 式钩子或插件的直接生命周期上报,或两者都要时,使用集成。完整的状态权威模型见[智能体](/zh-cn/docs/agents/)。 - -## 安装集成 - -在 Herdr 中打开设置,用集成标签页为 `PATH` 上发现的智能体安装推荐集成,或手动运行命令: - -```bash -herdr integration install pi -herdr integration install omp -herdr integration install claude -herdr integration install codex -herdr integration install copilot -herdr integration install devin -herdr integration install droid -herdr integration install kimi -herdr integration install opencode -herdr integration install kilo -herdr integration install hermes -herdr integration install mastracode -herdr integration install qodercli -herdr integration install cursor -``` - -## 卸载集成 - -```bash -herdr integration uninstall pi -herdr integration uninstall omp -herdr integration uninstall claude -herdr integration uninstall codex -herdr integration uninstall copilot -herdr integration uninstall devin -herdr integration uninstall droid -herdr integration uninstall kimi -herdr integration uninstall opencode -herdr integration uninstall kilo -herdr integration uninstall hermes -herdr integration uninstall mastracode -herdr integration uninstall qodercli -herdr integration uninstall cursor -``` - -## Herdr 如何使用集成 - -Herdr 以两种不同方式使用集成: - -| 集成类型 | 智能体 | 效果 | -| --- | --- | --- | -| 生命周期权威 | Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI、Hermes Agent、MastraCode | 已安装且在为该窗格主动上报时,由钩子或插件事件决定 `idle`、`working` 和 `blocked`。对同一个生命周期权威,Herdr 不再使用屏幕清单兜底。 | -| 会话身份 | Claude Code、Codex、GitHub Copilot CLI、Devin CLI、Droid、Qoder CLI、Cursor Agent CLI | 集成上报用于恢复的原生会话引用。状态仍来自 Herdr 的屏幕清单检测。 | - -自定义 socket 集成在定义了原生终端 UI 中不可见的状态时,也可以上报状态。 - -一些集成会上报智能体的原生会话引用。除非被 `[session] resume_agents_on_restore = false` 禁用,Herdr 会在服务器重启后使用官方会话引用恢复 Claude Code、Codex、Devin CLI、Droid、Kimi Code CLI、Qoder CLI、Cursor Agent CLI、GitHub Copilot CLI、Pi、OMP、Hermes Agent、OpenCode、Kilo Code CLI 和 MastraCode 的窗格。 - -原生会话恢复需要最新的 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`、Cursor Agent CLI 版本 `1`、OpenCode 版本 `5`、Kilo Code CLI 版本 `1`、Hermes Agent 版本 `2`、MastraCode 版本 `1`。用 `herdr integration status` 查看已安装版本。 - -## Pi - -安装 Pi 集成: - -```bash -herdr integration install pi -``` - -Herdr 把内置扩展写入: - -```text -~/.pi/agent/extensions/herdr-agent-state.ts -``` - -如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts`。如果 Pi agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。 - -## OMP - -安装 OMP 集成: - -```bash -herdr integration install omp -``` - -Herdr 把内置扩展写入: - -```text -~/.omp/agent/extensions/herdr-omp-agent-state.ts -``` - -如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts`。如果 OMP agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。 - -OMP 集成通过 Herdr 的 socket API 上报智能体标签 `omp`、生命周期状态和原生会话身份。它不需要对 `omp` 可执行文件做原生进程检测,并且 Herdr 可以在服务器重启后用 `omp --resume=<session>` 恢复 OMP 窗格。 - -## Claude Code - -安装 Claude Code 钩子: - -```bash -herdr integration install claude -``` - -该钩子在会话启动时把 Claude Code 的会话身份上报给本地 Herdr socket。Claude Code 的状态来自 Herdr 的屏幕清单检测。 - -Herdr 默认使用 `~/.claude`,设置了 `CLAUDE_CONFIG_DIR` 时使用后者。Claude 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并向 `settings.json` 添加 Herdr 钩子条目。卸载会移除匹配的钩子条目并删除钩子脚本。 - -## Codex - -安装 Codex 钩子: - -```bash -herdr integration install codex -``` - -Codex 钩子通过与其他集成相同的本地 socket API 上报会话身份。Codex 的状态来自 Herdr 的屏幕清单检测。 - -Herdr 默认使用 `~/.codex`,设置了 `CODEX_HOME` 时使用后者。Codex 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`、更新 `hooks.json`,并确保 `config.toml` 中有 `[features] hooks = true`。如果存在已弃用的顶层 `codex_hooks` 标志,它也会一并移除。卸载会从 `hooks.json` 中移除 Herdr 条目并删除钩子脚本,但不改动 `config.toml`。 - -## GitHub Copilot CLI - -安装 GitHub Copilot CLI 钩子: - -```bash -herdr integration install copilot -``` - -Copilot 钩子通过与其他集成相同的本地 socket API 上报会话身份。Copilot 的状态来自 Herdr 的屏幕清单检测。 - -Herdr 默认使用 `~/.copilot`,设置了 `COPILOT_HOME` 时使用后者。Copilot 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并向 `settings.json` 添加一个 `SessionStart` 钩子条目。卸载会从 `settings.json` 中移除 Herdr 条目并删除钩子脚本。 - -在 Copilot 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 `copilot --resume=<id>` 恢复该窗格。 - -## Devin CLI - -安装 Devin CLI 钩子: - -```bash -herdr integration install devin -``` - -该钩子从 Devin 的会话、提示、工具使用、权限和停止事件中上报原生会话身份。Devin 的状态仍来自 Herdr 的屏幕清单和 OSC 检测,因为 Devin 钩子不会在每次权限取消或用户中断后都发出可靠的状态转换。 - -Herdr 默认使用 `~/.config/devin`,设置了 `XDG_CONFIG_HOME` 时使用 `$XDG_CONFIG_HOME/devin`。Devin 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `config.json` 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 `config.json` 中移除 Herdr 条目并删除钩子脚本。 - -Herdr 用 `devin --resume <id>` 恢复保存的 Devin 会话。无论钩子是否安装,屏幕清单检测始终是状态权威。 - -## Kimi Code CLI - -安装 Kimi Code CLI 钩子: - -```bash -herdr integration install kimi -``` - -该钩子向 Herdr 上报 Kimi 的会话身份和生命周期状态,用于原生恢复和权威的 `idle`、`working`、`blocked` 状态。需要 Kimi Code CLI `0.14.0` 或更新版本。 - -Herdr 默认使用 `~/.kimi-code`,设置了 `KIMI_CODE_HOME` 时使用后者。Kimi Code 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并在 `config.toml` 中追加 Herdr 管理的 `[[hooks]]` 条目。卸载会移除 Herdr 管理的配置块并删除钩子脚本。 - -Herdr 用 `kimi --session <id>` 恢复保存的 Kimi 会话。 - -## Droid - -安装 Droid 钩子: - -```bash -herdr integration install droid -``` - -Droid 钩子通过与其他集成相同的本地 socket API 上报会话身份。生命周期状态仍来自 Herdr 的屏幕清单检测,因为 Droid 钩子没有覆盖所有生命周期转换。 - -Herdr 的 Droid 钩子使用 `~/.factory`。Factory 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,向 `settings.json` 添加 Herdr 的 `SessionStart` 钩子条目,并在 `hooks.json` 中存在旧的 Herdr Droid 钩子条目时将其移除。卸载会从两个配置文件中移除 Herdr 条目并删除钩子脚本。 - -在 Droid 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `droid --resume <id>` 恢复该窗格。 - -## OpenCode - -安装 OpenCode 插件: - -```bash -herdr integration install opencode -``` - -Herdr 把插件写入 `~/.config/opencode/plugins/herdr-agent-state.js`。OpenCode 配置目录必须已经存在。卸载只删除那个插件文件。 - -该插件在 OpenCode 运行于 Herdr 窗格内时上报生命周期状态和会话身份。在 OpenCode 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 `opencode --session <id>` 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。 - -## Kilo Code CLI - -安装 Kilo Code CLI 插件: - -```bash -herdr integration install kilo -``` - -Herdr 把插件写入 `~/.config/kilo/plugin/herdr-agent-state.js`。Kilo 配置目录必须已经存在。卸载只删除那个插件文件。 - -该插件在 Kilo 运行于 Herdr 窗格内时上报生命周期状态和会话身份。在 Kilo 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 `kilo --session <id>` 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。 - -## Hermes Agent - -安装 Hermes Agent 插件: - -```bash -herdr integration install hermes -``` - -Herdr 写入 `~/.hermes/plugins/herdr-agent-state/`,并在 `~/.hermes/config.yaml` 中启用 `herdr-agent-state`。Hermes 配置目录必须已经存在。安装后请重启 Hermes 以加载插件。卸载会删除插件目录,并从 `plugins.enabled` 中移除 `herdr-agent-state`。 - -该插件在 Hermes 运行于 Herdr 窗格内时上报生命周期、工具、审批状态和会话 id。Herdr 可以用上报的会话 id 通过 `hermes --resume <id>` 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。 - -## Qoder CLI - -安装 Qoder CLI 钩子: - -```bash -herdr integration install qodercli -``` - -该钩子向 Herdr 上报 Qoder CLI 的会话身份,用于原生恢复。生命周期状态仍来自 Herdr 的屏幕清单检测,因为 Qoder 钩子没有覆盖所有生命周期转换。 - -Herdr 默认使用 `~/.qoder`,设置了 `QODER_CONFIG_DIR` 时使用后者。Qoder 配置目录必须已经存在。安装会写入 `hooks/herdr-agent-state.sh`,并向 `settings.json` 添加 Herdr 钩子条目。卸载会移除匹配的钩子条目并删除钩子脚本。 - -Herdr 用 `qodercli --resume <id>` 恢复保存的 Qoder CLI 会话。 - -钩子未安装时,屏幕清单检测仍然可用。 - -## Cursor Agent CLI - -安装 Cursor Agent CLI 钩子: - -```bash -herdr integration install cursor -``` - -该钩子在 Cursor Agent CLI 运行于 Herdr 窗格内时,通过 Cursor 的 `sessionStart` 钩子上报会话身份。Cursor 的状态来自 Herdr 的屏幕清单检测。 - -Herdr 默认使用 `~/.cursor`,设置了 `CURSOR_CONFIG_DIR` 时使用后者。Cursor 配置目录必须已经存在。安装会写入 `herdr-agent-state.sh`,并向 `hooks.json` 添加 Herdr 的 `sessionStart` 条目。卸载会移除匹配的钩子条目并删除钩子脚本。 - -在 Cursor 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 `cursor-agent --resume <id>` 恢复该窗格。Herdr 恢复窗格时,`cursor-agent` 命令必须在 `PATH` 上;Herdr 不会启动通用的 `agent` 命令。 - -## MastraCode - -安装 MastraCode 钩子: - -```bash -herdr integration install mastracode -``` - -该钩子向 Herdr 上报 MastraCode 生命周期状态和线程身份,用于权威的 `idle`、`working`、`blocked` 状态和原生恢复。MastraCode 没有屏幕清单兜底;当 MastraCode 在 Herdr 窗格内运行时,状态来自该钩子。 - -Herdr 使用 `~/.mastracode`。安装会写入 `hooks/herdr-agent-state.sh`,并把 Herdr 命令条目添加到 `hooks.json`;目录不存在时会创建。卸载会删除匹配的钩子条目和钩子脚本。 - -Herdr 用 `mastracode --thread <id>` 恢复保存的 MastraCode 线程。 - -## 自定义状态标签 - -集成只把生命周期状态作为语义状态上报。例如,上报智能体为 `working` 时,不在生命周期报告中添加展示字段。 - -```bash -herdr pane report-agent w1:p1 \ - --source custom:docs \ - --agent docs-bot \ - --state working -``` - -与 Herdr 管理的集成并行运行的用户钩子,应该使用元数据而不是 `report-agent`。元数据只改变展示,不会夺走集成对 `idle`、`working`、`blocked` 或会话恢复的权威。`--agent` 和 `--applies-to-source` 只守卫展示字段 (`--title`、`--display-agent` 和 `--state-label`)。令牌补丁始终生效;上报方负责清除或刷新 TTL。`--display-agent` 修改显示名称。 - -```bash -herdr pane report-metadata "$HERDR_PANE_ID" \ - --source user:claude-title \ - --agent claude \ - --title "Refactor auth middleware" \ - --display-agent "Claude: auth" \ - --token summary="refactor auth" \ - --state-label working="refactoring auth" \ - --ttl-ms 3600000 -``` - -令牌和状态标签只影响视觉。等待、通知和工作区汇总仍使用语义状态。 - -## 调试集成状态 - -列出已知的智能体: - -```bash -herdr agent list -``` - -需要验证 Herdr 能看到什么时,读取窗格: - -```bash -herdr pane read w1:p1 --source recent --lines 50 -``` - -如果集成状态看起来不对,先确认智能体运行在 Herdr 内部,并且相关的钩子或插件是为同一个用户账号安装的。 diff --git a/website/src/content/docs/zh-cn/keyboard.mdx b/website/src/content/docs/zh-cn/keyboard.mdx deleted file mode 100644 index 0dfea960..00000000 --- a/website/src/content/docs/zh-cn/keyboard.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: 键盘 -description: 前缀键是什么、应该先学哪些绑定,以及如何做到不用前缀键。 ---- - -:::tip[从 tmux 或 zellij 迁移过来?] -这套模型你已经很熟悉了。直接跳到[按键绑定参考](/zh-cn/docs/configuration/#按键绑定)查看完整的默认键位和配置语法。 -::: - -Herdr 是鼠标原生的。你可以点击窗格、标签页、工作区和智能体,拖动分割边框,使用右键菜单,一个按键绑定都不用学。键盘操作是可选的一层,不是必需项。 - -## 前缀键是什么 - -终端复用器位于终端和其中运行的程序之间。这些程序已经占用了大多数按键组合: `ctrl+c` 中断,`ctrl+r` 搜索历史,编辑器几乎占用了剩下的一切。如果 Herdr 直接抢占常用按键,就会破坏其中运行的程序。 - -前缀键解决了这个问题。按下前缀键 (默认 `ctrl+b`),下一次按键会发给 Herdr 而不是终端。`prefix+c` 的意思是: 按下 `ctrl+b`,松开,再按 `c`。只保留一个键,而不是几十个。 - -随时按 `prefix+?` 可以查看所有生效的绑定。 - -## 先学这五个 - -| 动作 | 按键 | -| --- | --- | -| 新建标签页 | `prefix+c` | -| 向右 / 向下分割 | `prefix+v` / `prefix+minus` | -| 在窗格间移动 | `prefix+h/j/k/l` | -| 工作区导航 | `prefix+w` | -| 分离并让一切继续运行 | `prefix+q` | - -这些覆盖了日常的大部分移动操作。其余的都可以继续用鼠标。 - -## 其余的,按任务分 - -窗格: - -| 动作 | 按键 | -| --- | --- | -| 缩放聚焦的窗格 | `prefix+z` | -| 关闭窗格 | `prefix+x` | -| 交换窗格 | `prefix+shift+h/j/k/l` | -| 调整大小模式 | `prefix+r` | -| 复制模式 | `prefix+[` | - -标签页: - -| 动作 | 按键 | -| --- | --- | -| 下一个 / 上一个标签页 | `prefix+n` / `prefix+p` | -| 跳转到标签页 1–9 | `prefix+1..9` | -| 重命名标签页 | `prefix+shift+t` | -| 关闭标签页 | `prefix+shift+x` | - -工作区与会话: - -| 动作 | 按键 | -| --- | --- | -| 新建工作区 | `prefix+shift+n` | -| 重命名工作区 | `prefix+shift+w` | -| 关闭工作区 | `prefix+shift+d` | -| Goto 选择器 | `prefix+g` | -| 切换侧边栏 | `prefix+b` | - -完整键位和绑定语法见[按键绑定参考](/zh-cn/docs/configuration/#按键绑定)。 - -## 复制模式 - -按 `prefix+[` 让聚焦的窗格进入复制模式。用 `h/j/k/l`、tmux 风格的 `w/b/e` 和 `{`/`}` 移动。按 `/` 或 `?` 向前或向后进行文本搜索,再用 `n` 或 `N` 按相同或相反方向重复搜索。查询包含大写字母时区分大小写,否则不区分。用 `v` 或空格开始选择,用 `y` 或回车复制,用 `q` 或 Esc 不复制直接退出。Esc 会先清除当前选择或搜索,然后才退出。复制模式不会暂停窗格进程:停留在底部时继续跟随输出,进入历史记录后保持当前位置。鼠标拖选可以直接复制,完全不用进入复制模式。 - -## 一切都可以改 - -每个绑定都可以配置,包括前缀键本身: - -```toml -[keys] -prefix = "ctrl+a" -``` - -## 不用前缀键 - -你可以把 Herdr 动作绑定到完全不需要前缀的直接组合键。难点在于知道哪些组合键是安全的,因为终端、shell 和桌面环境已经占用了键盘的大部分。 - -任何组合键都可以做绑定: `ctrl+j`、`alt+k`,顺手就行。但一个组合键要经过三层才能到达 Herdr: 操作系统、外层终端 (Ghostty、iTerm2 等都带有自己的默认键位),以及窗格内运行的程序。`ctrl+j` 能顺利到达 Herdr,但 shell 和编辑器把它当作回车。`alt+k` 在 Linux 上是空闲的,但在 macOS 的大多数终端里会被组合成特殊字符。如果你从这些键系里选组合键,请对照自己的终端和系统快捷键再确认一遍。 - -我们梳理了 Ghostty、iTerm2、Terminal.app、kitty、WezTerm、Alacritty、Warp、Windows Terminal、GNOME Terminal 和 Konsole 的默认按键绑定,以及 GNOME 和 KDE 的全局快捷键。有一个修饰键系几乎在所有地方都没被占用: `ctrl+alt`。终端把它留空,它不受 macOS option 键组合行为 (会挡掉纯 `alt` 组合键) 的影响,而且即使在没有现代键盘协议的终端里也能正常传输。它是安全的默认推荐;选择权在你。 - -下面的配置保留前缀绑定,并在其上叠加直接组合键: - -```toml -[keys] -focus_pane_left = ["prefix+h", "ctrl+alt+h"] -focus_pane_down = ["prefix+j", "ctrl+alt+j"] -focus_pane_up = ["prefix+k", "ctrl+alt+k"] -focus_pane_right = ["prefix+l", "ctrl+alt+l"] -previous_tab = ["prefix+p", "ctrl+alt+["] -next_tab = ["prefix+n", "ctrl+alt+]"] -new_tab = ["prefix+c", "ctrl+alt+c"] -split_vertical = ["prefix+v", "ctrl+alt+d"] -split_horizontal = ["prefix+minus", "ctrl+alt+shift+d"] -zoom = ["prefix+z", "ctrl+alt+z"] -``` - -少数 `ctrl+alt` 组合键已被其他地方占用。请避开这些: - -| 组合键 | 占用者 | -| --- | --- | -| `ctrl+alt+arrows` | GNOME 工作区切换,Ghostty 和 Konsole 默认键位 | -| `ctrl+alt+t` | Ubuntu 和 Fedora 的“启动终端” | -| `ctrl+alt+l` / `ctrl+alt+a` | KDE 锁屏 / 注意力窗口 | -| `ctrl+alt+s` / `ctrl+alt+u` | Konsole | -| `ctrl+alt+f1..f12` | Linux 虚拟控制台切换 | - -如果某个直接组合键没有任何反应,说明终端或桌面环境在 Herdr 看到它之前就把它消费掉了。两边任选其一重新配置: 在终端设置里释放这个组合键,或者在 Herdr 里换一个。 diff --git a/website/src/content/docs/zh-cn/marketplace.mdx b/website/src/content/docs/zh-cn/marketplace.mdx deleted file mode 100644 index 350cc0d5..00000000 --- a/website/src/content/docs/zh-cn/marketplace.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: 插件市场 -description: 在 GitHub 上发现社区 Herdr 插件,并让你自己的插件被收录。 ---- - -Herdr 插件市场是一个可供发现的社区插件索引。 -访问 [herdr.dev/plugins](/plugins/) 浏览。它是公开 GitHub 仓库的自动索引, -而不是经过审核的目录。 - -## 浏览插件 - -[插件市场](/plugins/)会列出所有打了 GitHub 主题标签 `herdr-plugin` 的公开仓库。 -你可以按名称、作者、描述或语言搜索,并按热度、最近活跃度或最新排序。 -每个条目都直接链接到它在 GitHub 上的源码仓库。 - -收录是自动且未经审核的。被列出只说明仓库给自己打了标签,并不代表 Herdr -审查过它,所以在安装任何插件之前,请先阅读[信任指南](/zh-cn/docs/plugins/#信任与安全)。 - -## 安装插件 - -插件市场是在安装之上增加的发现渠道,它不会取代安装。任何插件都可以直接从 -GitHub 安装: - -```bash -herdr plugin install owner/repo[/subdir...] -``` - -发布一个普通的公开 GitHub 仓库,在根目录或子目录放一个 `herdr-plugin.toml` -清单,这条命令就能用了。清单和编写参考见[插件](/zh-cn/docs/plugins/)。 - -## 让你的插件被收录 - -给公开仓库添加 GitHub 主题标签 `herdr-plugin`。索引只使用这一个信号, -所以给公开插件打上标签就够了。索引每 30 分钟自动刷新,新打标签的仓库很快 -就会出现,去掉标签的仓库会在下一次刷新时消失。 - -## 条目会展示什么 - -每张卡片展示 GitHub 仓库的元数据: 仓库名和作者、描述、star 数、主要语言、 -最后 push 时间,以及指回源码的链接。索引从 GitHub 的仓库搜索读取这些信息, -所以保持仓库描述和主题标签的准确,是让条目有用的关键。 - -索引目前还不会解析 `herdr-plugin.toml`,所以插件 `id`、声明的 `platforms`、 -`min_herdr_version` 等清单字段在 v1 中不会展示。Fork 和已归档的仓库会被排除。 diff --git a/website/src/content/docs/zh-cn/persistence-remote.mdx b/website/src/content/docs/zh-cn/persistence-remote.mdx deleted file mode 100644 index a81a8469..00000000 --- a/website/src/content/docs/zh-cn/persistence-remote.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: 持久化与远程访问 -description: 从 Herdr 分离、稍后重新连接、使用命名会话,以及通过 SSH 连接。 ---- - -Herdr 让窗格在后台服务器中持续运行。你的终端客户端可以分离,稍后再重新连接。 - -关于本地、SSH 和 `herdr --remote` 工作流,参见[使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/)。 - -## 分离与重新连接 - -用 `ctrl+b q` 分离客户端;窗格和智能体继续运行。再次运行 `herdr` 即可重新连接。用 `herdr server stop` 停止会话及其窗格。 - -在服务器完全停止后再次启动时,Herdr 会恢复保存的会话形态。关于分离、服务器重启、屏幕历史回放、智能体原生会话恢复和实时交接各自能保留什么,参见[会话状态与恢复](/zh-cn/docs/session-state/)。 - -## 命名会话 - -需要相互独立的 Herdr 服务器时,使用命名会话。 - -```bash -herdr session list -herdr session attach work -herdr session attach side-project -herdr session stop work -herdr session delete side-project -``` - -命名会话拥有自己的窗格、标签页、工作区、socket 和运行时状态。它仍然共享同一个全局配置文件。 - -脚本中使用 `--json`: - -```bash -herdr session list --json -herdr session stop work --json -herdr session delete side-project --json -``` - -## 通过 SSH 远程连接 - -远程模式有两种;[使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/)对它们做了比较。tmux 风格的路径是 SSH 到服务器并在那里运行 `herdr`。另一种是从本地机器通过 SSH 连接: - -```bash -herdr --remote workbox -herdr --remote ssh://you@server:2222 -``` - -这种模式下,你本地的 Herdr 是瘦客户端。它通过 SSH 连接,启动或连接远程 Herdr 服务器,并把 UI 流式传回本地终端。因为客户端在本地运行,Herdr 可以把图像剪贴板粘贴等本地桌面功能桥接到远程会话: 把图像复制到远程临时文件,再粘贴该路径。 - -默认情况下,`herdr --remote` 在这次连接中使用你本地的 Herdr 按键绑定。即使远程服务器的配置不同,也能保持本地的肌肉记忆。本地按键绑定是连接时的快照;编辑本地按键绑定后请分离再重连。想改用远程服务器配置时,使用 `--remote-keybindings server`。本地的自定义命令按键绑定不会被发送,因为那些命令会在远程主机上执行。 - -对于经常连接的目标,使用你的 SSH 配置: - -```text -Host workbox - HostName server.example.com - User you - Port 2222 -``` - -然后这样连接: - -```bash -herdr --remote workbox -``` - -远程连接支持 x86_64 和 aarch64 的 Linux 与 macOS 主机。Herdr 会检查远程平台,优先使用远程 `PATH` 上已有的匹配 `herdr`,然后检查 `~/.local/bin/herdr`。如果没有匹配的二进制文件,交互式运行会询问是否安装到 `~/.local/bin/herdr`;非交互式运行则直接失败,不会修改主机。如果 `~/.local/bin` 不在远程 `PATH` 上,Herdr 会在安装后发出警告。 - -Windows 原生的 `herdr --remote` 不在 Windows 测试版范围内。在 Windows 上请 SSH 到服务器并在那里运行 `herdr`。 - -默认情况下,`herdr --remote` 通过一个临时 SSH 配置运行桥接: 先包含你的 SSH 配置,再补充兜底的保活设置。已有的用户保活设置优先。设置 `[remote].manage_ssh_config = false` 可以不用 Herdr 生成的桥接配置,而使用普通 `ssh`。 - -默认情况下,如果需要替换或重启运行中的远程服务器,远程连接使用常规的重启/停止流程。要对受支持的运行中远程服务器启用实验性实时交接,加上 `--handoff`: - -```bash -herdr --remote workbox --handoff -``` - -如果你先 SSH 到服务器再在那里运行 `herdr`,Herdr 就完全运行在服务器上。这种模式简单实用,但除了普通的终端文本粘贴之外,它无法访问你本地桌面的剪贴板。 - -当本地和远程平台一致时,对于直接安装,Herdr 可以直接复制当前本地二进制文件。对于 Homebrew、mise 和 Nix 安装,或平台不一致时,它会从 `https://herdr.dev/latest.json` 下载与当前客户端版本匹配的发布产物。 - -对于本地构建或自定义二进制文件,在远程连接前设置 `HERDR_REMOTE_BINARY` 指向本地文件路径。 - -```bash -HERDR_REMOTE_BINARY=target/release/herdr herdr --remote workbox -``` - -## 远程命名会话 - -用 `--session` 搭配 `--remote` 连接远程主机上的命名会话: - -```bash -herdr --remote workbox --session agents -``` - -## 直接终端附加 - -完整的 Herdr 连接会打开整个工作区 UI。直接附加则在你当前的终端中打开一个由服务器拥有的终端。 - -在 Windows 测试版中,直接终端附加仅限 Unix。 - -按智能体目标附加: - -```bash -herdr agent attach reviewer -``` - -按终端 ID 附加: - -```bash -herdr terminal attach term_abc123 -``` - -直接附加先流式传输当前渲染的终端状态,然后是实时 ANSI 帧。输入直接进入该终端。 - -用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。 - -一个终端只能有一个可写的直接附加客户端拥有输入和调整尺寸的权限。用 `--takeover` 替换现有的所有者: - -```bash -herdr terminal attach term_abc123 --takeover -``` - -## 单进程逃生舱 - -用 `--no-session` 在没有后台服务器/客户端分离的情况下运行 Herdr: - -```bash -herdr --no-session -``` - -这主要是调试或兼容性的逃生舱。默认的持久会话模式才是常规路径。 diff --git a/website/src/content/docs/zh-cn/plugins.mdx b/website/src/content/docs/zh-cn/plugins.mdx deleted file mode 100644 index 306bda53..00000000 --- a/website/src/content/docs/zh-cn/plugins.mdx +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: 插件 -description: 编写带有清单动作、事件钩子和窗格的本地 Herdr 插件。 ---- - -Herdr 插件是可分享、可执行的工作流包。插件可以是 Bash 脚本、JavaScript -应用、Lua 脚本、Rust 二进制,或你机器上能运行的任何 argv 命令。Herdr -负责宿主侧: 安装、清单校验、按键绑定、终端窗格、事件、调用上下文和 -socket 访问。插件负责自己的实现语言、依赖、文件和持久状态。 - -插件的存在是为了让 Herdr 保持精简。核心继续专注于终端工作区、窗格、 -智能体和稳定的 CLI/socket API。插件把这套已有的扩展面变成可复用的 -工作流,让大家可以构建、安装和分享,而不必把每种工作流都塞进 Herdr 本体。 - -插件不是 SDK 集成。它是一个带 `herdr-plugin.toml` 清单和 Herdr 可启动 -命令的目录。Herdr 校验清单、注入运行时上下文、启动声明的命令并记录日志。 -命令在需要做更多工作时,通过 CLI 或 socket 回调 Herdr。 - -没有单独的插件 SDK,也没有受限的命令集。整个 Herdr CLI 就是插件 API: -[CLI 参考](/zh-cn/docs/cli-reference/)中的每条命令插件都能用,你自己能以 -`herdr ...` 运行的任何东西,插件也能运行。大多数插件应通过指向运行中 -Herdr 二进制的 `HERDR_BIN_PATH` 调用 Herdr,这样插件在 Unix socket 和 -Windows 命名管道之间保持可移植。想自己发送原始 JSON 请求时,使用 -[socket API](/zh-cn/docs/socket-api/)。 - -运行时动作注册和非终端的原生插件 UI 不在插件 v1 范围内。动作、事件钩子、 -窗格和链接处理器都在清单中声明。 - -## 信任与安全 - -插件是运行在你机器上的普通代码。安装或链接一个插件时,它的构建和运行时 -命令以你的用户身份、在你的环境中执行,并且可以调用完整的 Herdr CLI — -和你给编辑器、shell 或编程智能体添加的任何扩展一样。这种开放性正是设计 -初衷,加上一点判断力就能保持安全。 - -从你信任的作者和仓库安装插件,并先大致看看新插件做什么: `herdr-plugin.toml` -清单,以及它运行的脚本或二进制。`herdr plugin install` 在交互式终端中会 -展示来源和将要运行的命令的预览,你可以在确认前审查。对已经信任的来源用 -`--yes`,想固定某个特定版本时用 `--ref`。 - -Herdr 校验清单,并把每个插件的配置和状态放在各自的目录中,但它不会审查 -或沙箱化插件的行为。第三方插件来自它们的作者,而不是 Herdr,审查与运行 -由你自行决定。 - -## 清单 - -清单是 Herdr 和插件之间的契约。它声明包元数据、支持的平台、可选的构建 -命令,以及 Herdr 可以运行的入口点。 - -```toml -id = "example.layout" -name = "Layout" -version = "0.1.0" -min_herdr_version = "0.7.0" -description = "Apply project layouts" -platforms = ["linux", "macos", "windows"] - -[[build]] -command = ["npm", "ci"] - -[[build]] -command = ["npm", "run", "build"] -platforms = ["linux", "macos"] - -[[startup]] -command = ["node", "dist/restore.js"] - -[[actions]] -id = "apply" -title = "Apply layout" -contexts = ["workspace"] -command = ["node", "dist/apply.js"] - -[[events]] -on = "worktree.created" -command = ["herdr", "workspace", "list"] - -[[panes]] -id = "board" -title = "Project board" -placement = "overlay" -command = ["herdr-board"] - -[[link_handlers]] -id = "github-issue" -title = "Open GitHub issue" -pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$" -action = "apply" -``` - -顶层的 `id`、`name`、`version` 和 `min_herdr_version` 是必填项。 -把 `min_herdr_version` 设为支持你插件所用的插件 API、事件名和清单字段的 -最老 Herdr 版本。当插件的最低版本比当前二进制更新时,Herdr 会拒绝链接 -或安装。`description` 可选。插件 id 可以使用 ASCII 字母、数字、点、 -冒号、下划线和连字符。 - -动作 id、窗格 id 和链接处理器 id 是插件内部的本地 id。它们可以使用 -ASCII 字母、数字、冒号、下划线和连字符,但不能用点。每种 id 在插件内 -必须唯一。当需要全局唯一名称时,Herdr 会把动作 id 限定为 -`plugin.id.action` 的形式。 - -用 `platforms = ["linux", "macos", "windows"]` 声明插件可以运行的平台。 -构建命令、启动钩子、动作、事件钩子、窗格和链接处理器也可以声明自己的 -`platforms`;条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地 -插件在链接时会给出警告。 - -`command` 的值是 argv 数组。Herdr 不会通过 shell 运行它们,所以除非你的 -命令自己启动 shell,否则没有 shell 展开。语言相关的行为放到你的脚本或 -二进制里。 - -## 第一个插件 - -从一个包含 `herdr-plugin.toml` 和一个可执行脚本或程序的目录开始: - -```text -my-plugin/ - herdr-plugin.toml - index.js -``` - -```toml -id = "example.workspace-tools" -name = "Workspace Tools" -version = "0.1.0" -min_herdr_version = "0.7.0" -description = "Small workspace helpers" -platforms = ["linux", "macos", "windows"] - -[[actions]] -id = "list-workspaces" -title = "List workspaces" -contexts = ["workspace"] -command = ["node", "index.js"] -``` - -在命令内部通过 `HERDR_BIN_PATH` 回调 Herdr: - -```js -const { spawnSync } = require("node:child_process"); - -const herdr = process.env.HERDR_BIN_PATH ?? "herdr"; -const result = spawnSync(herdr, ["workspace", "list"], { - encoding: "utf8", - stdio: ["ignore", "pipe", "pipe"], -}); - -process.stdout.write(result.stdout); -process.stderr.write(result.stderr); -process.exit(result.status ?? 1); -``` - -这个示例用了 Node,但插件本身完全不要求 Node。清单可以启动 Bash、 -PowerShell、Python、Rust、Go、Lua、Bun 或用户机器上可用的任何其他命令。 - -## 安装与链接 - -安装一个示例插件: - -```bash -herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify -herdr plugin config-dir examples.agent-telegram-notify -herdr plugin list -herdr plugin action list --plugin examples.agent-telegram-notify -``` - -在本地编写插件时,改为链接工作目录: - -```bash -herdr plugin link /path/to/plugin -herdr plugin config-dir example.layout -herdr plugin action list --plugin example.layout -herdr plugin action invoke example.layout.apply -herdr plugin pane open --plugin example.layout --entrypoint board -herdr plugin log list --plugin example.layout -``` - -`plugin install` 只接受 GitHub 简写,比如 `owner/repo/subdir`。它用 `git` -克隆,在交互式终端展示预览,运行受支持的构建命令,然后把检出保存到 -Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新安装 GitHub -管理的插件会替换该托管检出。已安装和已链接的插件及其启用状态对当前用户 -全局生效,可在所有 Herdr 会话中使用。即使 Herdr 服务器没有运行,也可以通过 -`plugin install` 和 `plugin link` 注册插件。仅安装在 Herdr 0.7.3 命名会话中的 -插件必须重新 install 或 link;现有的插件配置和状态会保留。 -不允许覆盖安装到本地链接的插件之上;请先 unlink 或 uninstall 本地插件。 -`plugin install` 和 `plugin link` 会创建 -插件的配置和状态目录,`plugin config-dir <id>` 打印配置目录,方便安装 -文档和 shell 脚本使用。 - -`plugin uninstall <id-or-source>` 注销插件。对 GitHub 管理的安装,它还会 -删除托管检出,并且既接受插件 id,也接受与 install 相同的 -`owner/repo[/subdir...]` 简写。`plugin unlink <id>` 只注销插件、不动文件, -对本地开发很有用。v1 没有单独的 `plugin update`;要刷新托管插件,请从 -GitHub 重新安装。 - -示例菜谱仓库是 `ogulcancelik/herdr-plugin-examples`。它在子目录中包含 -多个独立示例插件,包括 `agent-telegram-notify`、`github-link-preview` 和 -`dev-layout-bootstrap`。这些是供复制的示例,不是持续维护的官方插件。 - -## 构建命令 - -构建命令在 GitHub `plugin install` 过程中运行,时机在确认之后、Herdr -注册插件之前。如果构建命令失败,安装中止,插件不会被注册。`plugin link` -不运行构建命令;本地作者自己构建工作树。构建命令可以生成文件,但在 -安装预览之后修改 `herdr-plugin.toml` 会导致安装中止。构建失败时会显示 -插件 id、构建序号、工作目录、命令、退出状态或 spawn 错误,以及截断后的 -stdout/stderr,不会解读工具输出。 - -构建命令同样是普通的 argv 命令,但它们不会收到运行时插件上下文或 -Herdr socket 环境变量。插件作者应在文档中说明所需的系统工具,比如 -`cargo`、`npm`、`bun` 或 `lua`;Herdr 报告构建失败,但不会安装缺失的 -工具链。 - -## 启动钩子 - -Herdr 恢复会话且 API socket 就绪后,会为每个已启用插件运行一次 -`[[startup]]` 命令。实时交接由新服务器接管时会再次运行,但客户端连接、 -配置重载以及插件 link 或 enable 时不会运行。Herdr 异步启动这些命令,并在 -普通插件命令日志中记录完成情况。启动钩子失败不会停止服务器。 - -启动钩子是一次性初始化命令,不是受监督的守护进程。钩子应恢复插件自己的 -状态、调用所需的 Herdr API,然后退出。例如,插件可以把声明式 Agent 视图保存到 -`HERDR_PLUGIN_STATE_DIR`,再由启动钩子读取并重新应用。 - -启动钩子会收到普通运行时插件环境和 `HERDR_PLUGIN_EVENT=startup`。安装预览会 -列出所有启动命令,让用户检查将自动运行的代码。 - -## 命令与环境 - -运行时命令以插件目录为工作目录执行。Herdr 注入 `HERDR_SOCKET_PATH`、 -`HERDR_BIN_PATH`、`HERDR_ENV=1`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、 -`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、 -`HERDR_PLUGIN_CONTEXT_JSON`,以及可用时的 `HERDR_WORKSPACE_ID`、 -`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。动作命令还会收到 -`HERDR_PLUGIN_ACTION_ID`;启动钩子和事件钩子收到 `HERDR_PLUGIN_EVENT` -（启动钩子中的值为 `startup`）,事件钩子还会收到 -`HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。 - -`HERDR_PLUGIN_ROOT` 是已安装或已链接的插件目录。不要把用户凭据或持久 -状态放在那里,因为 GitHub 安装的插件根目录是托管的源码检出。把 `.env` -这类用户可编辑的配置放在 `HERDR_PLUGIN_CONFIG_DIR` 下,把本地运行时 -状态放在 `HERDR_PLUGIN_STATE_DIR` 下。Herdr 会创建这些目录,并在旧版 -插件配置位置存在时把内容初始化到 `HERDR_PLUGIN_CONFIG_DIR`,但不会校验、 -同步或删除其中的内容。文件格式和生命周期归插件所有。 - -`HERDR_PLUGIN_CONTEXT_JSON` 在本次调用可用时,可以包含工作区、标签页、 -聚焦窗格、worktree、智能体、选中文本、点击的 URL 和链接处理器字段。 -shell 插件可以从各个环境变量读取常用 id,或解析上下文 JSON 获取完整结构。 - -当插件需要从 Node、PowerShell、Bash 或其他运行时可移植地调用 Herdr 时, -使用 `HERDR_BIN_PATH`。`HERDR_SOCKET_PATH` 背后的原始 socket 传输是 -操作系统相关的: Unix 客户端连接 Unix socket 路径,Windows 客户端连接 -命名管道。通过 `HERDR_BIN_PATH` 的 CLI 调用可以避开这种传输差异。可用 -命令见 [CLI 参考](/zh-cn/docs/cli-reference/),原始请求结构见 -[socket API](/zh-cn/docs/socket-api/)。 - -## 窗格 - -清单中窗格的 `placement` 默认为 `overlay`,它在活动窗格上方打开一个 -临时的缩放覆盖层,关闭时恢复之前的焦点和缩放。`plugin.pane.open` 请求 -可以用 `overlay`、`popup`、`split`、`tab` 或 `zoomed` 覆盖清单的 placement。 - -`placement = "popup"` 会打开一个会话级模态终端弹窗,而不改变平铺布局。 -可以在清单或 open 请求中指定可选的 `width` 和 `height`;省略时默认为终端大小的一半,数字表示外层终端单元格数,`"80%"` 这样的字符串表示终端区域的百分比。 -弹窗会接收包括 Escape 在内的所有终端输入,并在命令退出或发送 `popup.close` 请求时关闭。 -小于弹窗最小尺寸的值会限制为最小值。 - -如果某个插件窗格应始终是临时的,可直接在入口点上声明 placement: - -```toml -[[panes]] -id = "picker" -title = "Picker" -platforms = ["linux", "macos"] -placement = "popup" -width = "80%" -height = 20 -command = ["sh", "picker.sh"] -``` - -split、tab、zoomed 和 overlay 插件窗格打开后就是普通的 Herdr 窗格。插件可以通过 socket 或 CLI 调用 -`pane.move`、`pane.swap`、`pane.resize`、`pane.zoom` 等标准窗格 API; -窗格跨标签页或工作区移动时,Herdr 会让插件窗格的所有权跟随底层窗格。 -弹窗不是 Herdr 窗格,而是会话级单例资源:它没有窗格 id,不会改变插件焦点上下文,不会发出窗格生命周期事件,也不参与 pane、layout、持久化或智能体 API。 -其进程不会收到 `HERDR_PANE_ID`;底层平铺窗格仍可通过 `HERDR_PLUGIN_CONTEXT_JSON` 获取。 -在 Settings、复制模式或其他 Herdr 模态界面打开时尝试打开弹窗会返回 `ui_busy`;启动成功后,`plugin.pane.open` 返回 `ok`。 - -在 Windows 上,构建命令、动作命令和事件命令会在裸命令位于 `PATH` 上时 -解析常见的 `PATHEXT` shim,比如 `npm.cmd`、`bun.cmd` 和 `pnpm.cmd`。 -窗格命令使用 Herdr 常规的 Windows 窗格启动器,仍然必须是有效的 Windows -argv 命令。 - -## 按键绑定 - -把某个键绑定到已安装的插件动作: - -```toml -[[keys.command]] -key = "prefix+l" -type = "plugin_action" -command = "example.layout.apply" -description = "apply layout" -``` - -## 链接处理器 - -用 `[[link_handlers]]` 把对匹配终端 URL 的修饰键点击路由到插件动作, -而不是在浏览器中打开 URL。修饰键点击的修饰键在所有平台上都是 Control, -包括 macOS,因为被捕获的终端鼠标上报无法把 Command/Super 和普通点击 -区分开。`pattern` 是对被点击 URL 匹配的 Rust 正则表达式,`action` 必须 -指向同一插件声明的动作。链接处理器动作在 `HERDR_PLUGIN_CONTEXT_JSON` -中收到 `invocation_source = "link_click"`、`clicked_url` 和 -`link_handler_id`;shell 插件也可以读取 `HERDR_PLUGIN_CLICKED_URL` 和 -`HERDR_PLUGIN_LINK_HANDLER_ID`。每个插件内的处理器按清单顺序检查。 - -## 存储 - -v1 没有 Herdr 管理的插件存储 API。需要持久状态的插件应自己管理文件或 -数据库。 - -## 插件市场 - -社区插件可以在[插件市场](/plugins/)中发现,它是打了 `herdr-plugin` 主题 -标签的公开 GitHub 仓库的自动索引。插件仍然是普通的 GitHub 仓库: 发布一个 -带 `herdr-plugin.toml` 的仓库,然后分享 -`herdr plugin install owner/repo[/subdir]`。 - -要让插件被收录,给它的公开仓库添加 GitHub 主题标签 `herdr-plugin`。索引 -每 30 分钟刷新一次。发现机制的工作方式见[插件市场](/zh-cn/docs/marketplace/)。 diff --git a/website/src/content/docs/zh-cn/quick-start.mdx b/website/src/content/docs/zh-cn/quick-start.mdx deleted file mode 100644 index 3f695d92..00000000 --- a/website/src/content/docs/zh-cn/quick-start.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: 快速开始 -description: 创建你的第一个 Herdr 工作区,在持久的终端窗格中运行智能体。 ---- - -如果还没有安装 Herdr,请参见[安装](/zh-cn/docs/install/)。然后在任意项目目录中启动 Herdr: - -```bash -herdr -``` - -Herdr 会启动或连接到你的默认后台会话。你不需要管理 socket。即使分离,智能体也会继续运行。 - -## 创建工作区 - -当会话中没有工作区时,Herdr 会自动打开一个。工作区是项目级别的容器,容纳标签页、窗格和智能体。给每个活跃项目一个独立的工作区,这样侧边栏里的智能体状态才清晰可读。 - -## 使用鼠标 - -Herdr 是鼠标原生的,所以从点击开始。点击窗格、标签页、工作区和智能体来聚焦它们。拖动分割边框来调整大小。右键打开上下文菜单,包括分割窗格和创建标签页。拖选文本即可复制到剪贴板;双击一个词直接复制它。复制不需要 Ctrl+C。 - -当终端把带修饰键的点击传给 Herdr 时,Ctrl+点击可以打开窗格内的链接。这对 OSC 8 超链接和可见的 `http://` 或 `https://` URL 有效。在 macOS 上,鼠标捕获开启时,请用 Ctrl+点击来触发 Herdr 处理的窗格链接;Cmd+点击只能通过终端原生的绕过路径使用,比如 Shift+Cmd+点击或 `ui.mouse_capture = false`。 - -如果配置了 `ui.right_click_passthrough_modifier`,该修饰键加右键会把右键点击、按住和拖动手势发送给启用鼠标上报的窗格应用。 - -## 运行智能体 - -在窗格里启动你的编程智能体: - -```bash -claude -``` - -也可以是 `codex`、`pi`、`opencode` 或任何其他[受支持的智能体](/zh-cn/docs/agents/)。Herdr 会自动检测。侧边栏会显示每个智能体处于 `working`、`blocked`、`done` 还是 `idle` — 并且跨所有工作区显示,所以你总能知道哪个项目需要你。 - -## 键盘操作 - -键盘操作是可选的;鼠标可以完成一切。按 `ctrl+b` 进入前缀模式,然后按一个动作键。 - -常用动作: - -| 动作 | 按键 | -| --- | --- | -| 向右分割 | `prefix+v` | -| 向下分割 | `prefix+minus` | -| 新建标签页 | `prefix+c` | -| 下一个 / 上一个标签页 | `prefix+n` / `prefix+p` | -| 工作区导航 | `prefix+w` | -| 新建工作区 | `prefix+shift+n` | -| 分离客户端 | `prefix+q` | - -第一次接触前缀键的概念?[键盘](/zh-cn/docs/keyboard/)会解释它是什么、为什么终端复用器要用它,以及如何做到不用前缀键。在 Herdr 里按 `prefix+?` 查看所有生效的绑定,按 `prefix+[` 进入复制模式用键盘复制。 - -## 分离与回来 - -按 `prefix+q`,或者直接关掉终端窗口。Herdr 服务器和所有智能体会继续运行。再次运行 `herdr` 即可重新连接到同一个会话。 - -要真正结束会话并停止其中的窗格: - -```bash -herdr server stop -``` - -## 接下来 - -- [核心概念](/zh-cn/docs/concepts/) — 两分钟了解工作区、标签页、窗格和智能体模型。 -- [使用 Herdr 的工作方式](/zh-cn/docs/how-to-work/) — 本地、SSH、手机和 `herdr --remote` 工作流。 -- [智能体](/zh-cn/docs/agents/) — 受支持的智能体、检测,以及提升状态准确度的集成。 -- [配置](/zh-cn/docs/configuration/) — 按键绑定、主题、通知,以及其他一切。 diff --git a/website/src/content/docs/zh-cn/session-state.mdx b/website/src/content/docs/zh-cn/session-state.mdx deleted file mode 100644 index cf796d0c..00000000 --- a/website/src/content/docs/zh-cn/session-state.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: 会话状态与恢复 -description: 理解 Herdr 保持哪些实时状态、重启后恢复什么、从历史回放什么、通过智能体集成恢复什么会话,以及更新时如何交接。 ---- - -Herdr 有多条状态路径,它们解决的是不同的问题。 - -## 什么能保留下来 - -| 场景 | 进程继续运行 | 布局恢复 | 最近的屏幕内容恢复 | 智能体对话恢复 | -| --- | --- | --- | --- | --- | -| 分离并重新连接 | 是 | 是 | 是,来自实时终端 | 是,因为进程从未停止 | -| 服务器重启 | 否 | 是 | 仅在开启窗格屏幕历史时 | 仅在有智能体原生会话恢复时 | -| 不带 `--handoff` 的更新 | 兼容的服务器继续运行;需要重启的服务器可能要停止/重启 | 重启后恢复 | 仅在开启窗格屏幕历史时 | 仅在有智能体原生会话恢复时 | -| 带 `--handoff` 的更新 | 对受支持的运行中服务器尽力而为 | 是 | 是,交接成功时来自实时终端 | 是,交接成功时进程保持运行 | - -下面的小节逐一解释这些路径。 - -## 实时持久化 - -普通分离会让 Herdr 服务器继续运行。窗格、shell、智能体、服务器、测试和命令进程都在该服务器中继续运行。 - -用 `ctrl+b q` 分离客户端。之后重新连接: - -```bash -herdr -``` - -这是最强的持久化路径,因为原始进程从未停止。 - -## 快照恢复 - -如果 Herdr 服务器停止后再启动,原来的窗格进程已经不在了。Herdr 会恢复保存的会话形态: 工作区、标签页、窗格、cwd、布局和焦点。 - -快照恢复不会保留运行中的 shell、服务器、测试或任意进程。无法使用更强恢复路径的窗格,会在各自保存的目录中作为新 shell 回来。 - -## 窗格屏幕历史回放 - -窗格屏幕历史在服务器完全重启后恢复最近的终端内容。它恢复的是 Herdr 能展示的内容,而不是原来的进程。 - -它默认关闭,因为窗格输出可能包含密钥、令牌、提示词和命令输出。可以在 Settings > Experiments > pane screen history 中开启,或者: - -```toml -[experimental] -pane_history = true -``` - -开启后,Herdr 把保存的窗格历史存放在 `session.json` 旁边的 `session-history.json` 中。请像对待终端历史一样对待 Herdr 的配置/会话目录。 - -## 智能体原生会话恢复 - -一些智能体可以恢复它们自己的对话会话。Herdr 可以使用官方集成上报的会话引用,在 Herdr 服务器重启后重新启动受支持的智能体窗格。 - -这默认开启。关闭方法: - -```toml -[session] -resume_agents_on_restore = false -``` - -Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引用的窗格。 - -当客户端连接并提供终端尺寸和主题上下文后,Herdr 会跨工作区和标签页恢复符合条件的智能体窗格,不需要等每个窗格被聚焦。 - -智能体原生会话恢复需要以下版本或更新的 Herdr 集成: - -| 智能体 | 最低 Herdr 集成版本 | 恢复命令 | -| --- | --- | --- | -| Pi | `2` | `pi --session <path-or-id>` | -| OMP | `3` | `omp --resume=<path-or-id>` | -| Claude Code | `6` | `claude --resume <id>` | -| Codex | `5` | `codex resume <id>` | -| Cursor Agent CLI | `1` | `cursor-agent --resume <id>` | -| GitHub Copilot CLI | `2` | `copilot --resume=<id>` | -| Devin CLI | `2` | `devin --resume <id>` | -| Droid | `2` | `droid --resume <id>` | -| Kimi Code CLI | `3` | `kimi --session <id>` | -| Qoder CLI | `2` | `qodercli --resume <id>` | -| OpenCode | `5` | `opencode --session <id>` | -| Kilo Code CLI | `1` | `kilo --session <id>` | -| Hermes Agent | `2` | `hermes --resume <id>` | -| MastraCode | `1` | `mastracode --thread <id>` | - -运行 `herdr integration status` 查看已安装的集成版本。用 `herdr integration install <agent>` 重新安装过期的集成。 - -不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。 - -如果某个窗格适用智能体原生会话恢复,Herdr 会对该窗格恢复智能体会话,而不是回放保存的窗格历史。 - -## 实时交接 - -实时交接用于需要替换运行中 Herdr 服务器的更新和远程连接流程。它请求旧服务器把实时窗格转移给新服务器,让窗格进程跨服务器替换继续运行。 - -这与快照恢复、窗格历史回放和智能体原生会话恢复不同。交接尝试让当前进程活下去,其他路径则是在旧服务器已经停止之后重建状态。 - -交接保护的是由服务器拥有的长期会话状态:窗格 PTY 和进程、智能体身份与持久元数据,以及替换服务器所需的插件/会话状态。它不会跨替换边界保留临时协调状态。进行中的 CLI 或 API 请求、等待、订阅流、客户端套接字和窗格间消息可能会中断;客户端应重新连接并重试。 - -实时交接是实验性功能,需要主动开启: - -```bash -herdr update --handoff -herdr --remote workbox --handoff -``` - -普通的 `herdr update` 和普通的 `herdr --remote workbox` 默认使用常规的重启/停止流程。 - -`herdr update --handoff` 只适用于由 Herdr 自带更新器管理的安装。Homebrew、mise 和 Nix 安装通过各自的包管理器更新,因此那些安装中 `herdr update` 被禁用,无法执行实时交接。 diff --git a/website/src/content/docs/zh-cn/socket-api.mdx b/website/src/content/docs/zh-cn/socket-api.mdx deleted file mode 100644 index 2077d571..00000000 --- a/website/src/content/docs/zh-cn/socket-api.mdx +++ /dev/null @@ -1,746 +0,0 @@ ---- -title: Socket API -description: 从脚本、工具和编程智能体控制运行中的 Herdr 服务器。 ---- - -Herdr 为需要检查或控制运行中会话的脚本和智能体提供了一个本地 socket API。 - -大多数自动化应从 CLI 包装命令开始。只有在需要直接的请求/响应控制或长期事件订阅时,才使用原始 socket API。 - -## 选择集成层 - -| 层 | 用途 | -| --- | --- | -| 智能体技能 | 教编程智能体如何在窗格内使用 Herdr。 | -| CLI 包装 | Shell 脚本、简单编排和人工调试。 | -| 原始 socket API | 自定义工具、协议客户端和事件订阅者。 | - -这些层共享同一套控制面。 - -## Schema - -安装的 CLI 可以打印该 Herdr 二进制中包含的 socket 协议 schema: - -```bash -herdr api schema -herdr api schema --json -herdr api schema --output herdr-api.schema.json -``` - -普通的 `herdr api schema` 打印简短摘要。`--json` 打印供工具使用的完整 JSON Schema,`--output PATH` 将该文档写入文件。schema 覆盖原始请求、成功响应、错误响应、发出的事件和订阅事件。 - -## 你能控制什么 - -socket API 可以: - -- 创建、列出、聚焦、重命名和关闭工作区 -- 创建、列出、聚焦、重命名和关闭标签页 -- 列出、检查、分割、交换、聚焦、调整、重命名、读取、关闭窗格并向其发送输入 -- 通过 CLI 辅助命令列出、检查、读取、提示、等待、重命名、聚焦、启动和附加智能体 -- 从钩子和插件上报自定义智能体状态 -- 订阅事件并等待输出或状态变化 -- 安装和卸载内置集成 -- 停止服务器并重载配置 - -## CLI 示例 - -创建工作区: - -```bash -herdr workspace create --cwd ~/project --label api -``` - -创建标签页: - -```bash -herdr tab create --label logs -``` - -分割窗格并运行命令: - -```bash -herdr pane split w1:p1 --direction right -herdr pane run w1:p2 "npm test" -``` - -检查并重排窗格: - -```bash -herdr pane layout --current -herdr pane neighbor --direction right --current -herdr pane resize --direction right --amount 0.1 --current -herdr pane swap --direction right --current -herdr pane zoom --on --current -herdr pane split w1:p1 --direction right --ratio 0.333 -``` - -等待智能体: - -```bash -herdr agent wait w1:p1 --until done -``` - -读取窗格输出: - -```bash -herdr pane read w1:p2 --source recent --lines 50 -``` - -## 原始方法 - -原始 socket 方法名使用点号记法: - -| 领域 | 方法 | -| --- | --- | -| 服务器 | `ping`、`server.stop`、`server.reload_config`、`server.agent_manifests`、`server.reload_agent_manifests` | -| 通知 | `notification.show` | -| 客户端 | `client.window_title.set`、`client.window_title.clear` | -| 会话 | `session.snapshot` | -| 工作区 | `workspace.create`、`workspace.list`、`workspace.get`、`workspace.focus`、`workspace.rename`、`workspace.move`、`workspace.report_metadata`、`workspace.close` | -| Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` | -| 标签页 | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.move`、`tab.close` | -| 窗格 | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.graphics.info`、`pane.graphics.set`、`pane.graphics.clear`、`pane.graphics.stream`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` | -| 弹窗 | `popup.close` | -| 布局 | `layout.export`、`layout.apply`、`layout.set_split_ratio` | -| 智能体 | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send_keys`、`agent.prompt`、`agent.wait`、`agent.rename`、`agent.focus`、`agent.start` | -| 事件 | `events.subscribe`、`events.wait` | -| 集成 | `integration.install`、`integration.uninstall` | -| 插件 | `plugin.link`、`plugin.list`、`plugin.unlink`、`plugin.enable`、`plugin.disable`、`plugin.action.list`、`plugin.action.invoke`、`plugin.log.list`、`plugin.pane.open`、`plugin.pane.focus`、`plugin.pane.close` | - -`agent.wait` 由服务器拥有并由事件驱动。它会固定到已解析的窗格占用者,因此替换后的智能体不能满足该等待。`agent.prompt` 接受可选的 `wait` 对象,其中包含 `until` 和 `timeout_ms`;这样可在一个请求中提交提示并开始等待,避免两个独立调用之间的竞态。 - -`session.snapshot` 为维护本地运行时缓存的客户端返回一次性引导快照。响应包含版本/协议元数据、当前聚焦的工作区/标签页/窗格 id、工作区记录、标签页记录、窗格记录、标签页布局快照和智能体记录。它不是订阅;读取后应订阅资源事件,并根据事件更新本地缓存。重新连接后或本地缓存可能已过期时,再次调用 `session.snapshot`。工作区记录也包含关联 worktree 的来源信息。完整的仓库 worktree 发现仍使用 `worktree.list`。 - -CLI 的 `herdr api snapshot` 会把当前 `session.snapshot` 响应输出为 JSON,让客户端和智能体可以简单地完成引导。 - -窗格控制方法使用 `w1:p1` 这类公开窗格 id。schema 中 `pane_id` 可选的方法,在省略它时使用服务器当前聚焦的活动窗格。`pane.move` 总是要求来源 `pane_id`。 - -`pane.send_keys` 和 `pane.send_input.keys` 接受 Herdr 组合键字符串: 普通可打印键、`enter` 和 `esc` 这类特殊键、`ctrl+h`、`control+j`、`alt+x`、`shift+tab` 这类修饰组合键、`f1` 这类功能键,以及 `minus` 和 `plus` 这类命名标点。它们不接受 `prefix+` 绑定字符串。 - -```json -{"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}} -{"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}} -{"id":"req_neighbor","method":"pane.neighbor","params":{"pane_id":"w1:p1","direction":"right"}} -{"id":"req_edges","method":"pane.edges","params":{"pane_id":"w1:p1"}} -{"id":"req_focus","method":"pane.focus_direction","params":{"direction":"right"}} -{"id":"req_resize","method":"pane.resize","params":{"pane_id":"w1:p1","direction":"right","amount":0.1}} -{"id":"req_zoom","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"toggle"}} -{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"env":{"HERDR_ROLE":"tests"}}} -{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}} -``` - -`pane.current` 返回单个 `PaneInfo`。带有 `caller_pane_id` 时,Herdr 返回那个窗格。省略时,Herdr 返回当前聚焦的活动窗格。 - -终端滚动指标可用时,`PaneInfo` 包含 `scroll`: - -```json -{ - "offset_from_bottom": 12, - "max_offset_from_bottom": 240, - "viewport_rows": 30 -} -``` - -客户端可以把 `offset_from_bottom == 0` 视为位于底部。 - -### 实验性窗格图形 - -窗格图形允许插件在窗格上放置图像数据。它们只在 `[experimental].kitty_graphics = true` 时可用;否则所有窗格图形方法都返回 `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"}} -{"id":"graphics_set","method":"pane.graphics.set","params":{"pane_id":"w1:p1","format":"png","image_width":800,"image_height":600,"data_base64":"...","placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}}} -{"id":"graphics_clear","method":"pane.graphics.clear","params":{"pane_id":"w1:p1"}} -``` - -要重复发送帧,用 `pane.graphics.stream` 打开专用 socket。Herdr 回复 `ok` 后,每一帧发送一个 JSON 头,再发送恰好 `data_length` 字节的原始数据。socket 关闭前,该流拥有对应窗格的图形层;并发 set、clear 或 stream 请求返回 `stream_conflict`。 - -```json -{"id":"graphics_stream","method":"pane.graphics.stream","params":{"pane_id":"w1:p1"}} -{"format":"png","image_width":800,"image_height":600,"data_length":12345,"placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}} -``` - -`pane.layout` 返回标签页布局快照,包含 `workspace_id`、`tab_id`、`zoomed`、外层 `area`、`focused_pane_id`、窗格矩形和分割矩形/比例。`pane.neighbor` 和 `pane.edges` 也包含同一份布局快照,让客户端不需要私有布局状态就能做出下一步决策。 - -`pane.process_info` 返回窗格的 shell pid、可用时的前台进程组 id,以及平台暴露时带有 pid、名称、argv/cmdline 和 cwd 的前台进程。 - -`layout.export` 返回可移植的标签页布局树。省略 `tab_id` 和 `pane_id` 导出活动标签页,传 `tab_id` 导出该标签页,或传 `pane_id` 导出包含该窗格的标签页。 - -```json -{"id":"req_export","method":"layout.export","params":{"tab_id":"w1:t1"}} -``` - -响应包含 `workspace_id`、`tab_id`、`zoomed`、`focused_pane_id` 和 `root`。`root` 是由 `pane` 和 `split` 节点组成的 BSP 树。窗格节点可以包含 `pane_id`、`label`、`cwd` 和 argv `command`。分割节点使用 `direction` (`right` 或 `down`)、`ratio`、`first` 和 `second`。 - -`layout.apply` 从声明式的树创建一个新标签页。提供 `tab_id` 时,Herdr 先创建替代标签页,再关闭旧标签页。它会恢复结构、标签、cwd、env 和可选的 argv 命令;不会保留活跃的 PTY、回滚内容或运行中的进程。 - -```json -{ - "id": "req_apply", - "method": "layout.apply", - "params": { - "workspace_id": "wabc", - "tab_label": "dev", - "focus": true, - "root": { - "type": "split", - "direction": "right", - "ratio": 0.65, - "first": { - "type": "pane", - "label": "editor", - "cwd": "/repo" - }, - "second": { - "type": "pane", - "label": "tests", - "cwd": "/repo", - "command": ["sh", "-c", "just test"], - "env": { "HERDR_ROLE": "tests" } - } - } - } -} -``` - -`layout.set_split_ratio` 更新标签页布局中已有分割的比例。响应是 `type: "layout_split_ratio_set"`,并包含更新后的可移植 `layout`。 - -```json -{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}} -``` - -启动进程的方法接受一个 `env` 对象。Herdr 只把这些键值对应用到新启动的进程。Herdr 还向受管窗格进程注入 `HERDR_SOCKET_PATH`、`HERDR_ENV=1`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID` 和 `HERDR_PANE_ID`。与调用方提供的环境变量冲突时,Herdr 管理的变量保持权威。 - -`pane.swap` 支持按方向和显式两种形式: - -```json -{"id":"req_swap_dir","method":"pane.swap","params":{"pane_id":"w1:p1","direction":"right"}} -{"id":"req_swap_explicit","method":"pane.swap","params":{"source_pane_id":"w1:p1","target_pane_id":"w1:p2"}} -``` - -交换仅限同一标签页。它保留分割形状、分割比例、窗格 id 和运行中的进程。响应是 `type: "pane_swap"`,带 `changed`、可选的 `reason`、`source_pane_id`、可选的 `target_pane_id`、`focused_pane_id` 和 `layout`。reason 的取值有 `no_neighbor`、`same_pane`、`not_found` 和 `cross_tab`。标签页处于缩放状态时,交换保持缩放,并修改隐藏的整页布局。 - -`pane.move` 把运行中的窗格移动到另一个标签页、新标签页或新工作区: - -```json -{"id":"req_move_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"tab","tab_id":"w1:t2","target_pane_id":"w1:p3","split":"right","ratio":0.5},"focus":true}} -{"id":"req_move_new_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_tab","workspace_id":"w1","label":"logs"},"focus":true}} -{"id":"req_move_new_workspace","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_workspace","label":"logs","tab_label":"main"},"focus":true}} -``` - -移动到已有标签页需要 `split: "right" | "down"`。`target_pane_id` 可选,默认是目标标签页的聚焦窗格。同一标签页内的布局变化仍然用 `pane.swap`;移动到来源标签页返回 `changed: false` 和 `reason: "same_tab"`。涉及缩放状态的来源或目标标签页的移动返回 `changed: false` 和 `reason: "zoomed_tab"`。 - -响应是 `type: "pane_move"`,带 `changed`、可选的 `reason`、`previous_pane_id`、`previous_workspace_id`、`previous_tab_id`、被移动的 `pane`、可选的 `source_layout`、`target_layout`、可选的新建工作区或标签页记录、可选的已关闭工作区或标签页 id,以及 `focused_pane_id`。跨工作区移动保持内部窗格和终端存活,但在目标工作区分配新的公开窗格 id。订阅者可以监听 `pane.moved`;Herdr 不会为被移动的终端进程发出假的窗格关闭/创建事件。 - -`pane.zoom` 切换、启用或禁用目标窗格所在标签页的缩放: - -```json -{"id":"req_zoom_toggle","method":"pane.zoom","params":{"pane_id":"w1:p1"}} -{"id":"req_zoom_on","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"on"}} -{"id":"req_zoom_off","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"off"}} -``` - -省略 `pane_id` 时,目标是服务器当前聚焦的活动窗格。响应是 `type: "pane_zoom"`,带 `changed`、`zoom_changed`、`focus_changed`、可选的 `reason`、`pane_id`、`focused_pane_id`、`zoomed` 和 `layout`。缩放状态或焦点任一发生变化时,`changed` 为 true。reason 的取值有 `single_pane`、`already_zoomed` 和 `already_unzoomed`。 - -`notification.show` 的 CLI 包装是: - -```bash -herdr notification show "build failed" --body "api workspace" --position top-left --sound request -``` - -通过配置的 toast 投递方式显示用户通知: - -```json -{"id":"req_notify","method":"notification.show","params":{"title":"build failed","body":"api workspace","position":"top-left","sound":"request"}} -``` - -`title` 必填,并且在移除控制字符和重复空白后必须仍有可见文本。`body` 可选。Herdr 把换行、制表符、回车和重复空白折叠为空格,然后把通知文本截断: `title` 80 个字符,`body` 240 个字符。净化后为空的 `title` 返回 `invalid_params`。`position` 可选,只在 `ui.toast.delivery = "herdr"` 时生效;桌面位置相对于完整的 Herdr 画面,省略时使用 `ui.toast.herdr.position`。terminal、system 和 off 投递忽略 `position`。`sound` 可选,取值 `none`、`done` 或 `request`;默认 `none`,且只在通知实际显示时播放。 - -响应会报告是否有内容被显示: - -```json -{"id":"req_notify","result":{"type":"notification_show","shown":true,"reason":"shown"}} -``` - -可能的 reason 有 `shown`、`disabled`、`rate_limited`、`no_foreground_client` 和 `busy`。`disabled` 表示 `ui.toast.delivery = "off"`。`busy` 表示已有的应用内 toast 未被替换。terminal 和 system 投递是通过当前前台连接的 Herdr 客户端尽力而为的。 - -设置或清除前台客户端的外层终端窗口标题: - -```json -{"id":"req_title","method":"client.window_title.set","params":{"title":"herdr api"}} -{"id":"req_title_clear","method":"client.window_title.clear","params":{}} -``` - -`client.window_title.clear` 恢复 Herdr 的默认标题。响应是 `type: "client_window_title"`,带 `changed` 和 `set`、`cleared` 或 `no_foreground_client` 之一的 reason。 - -Worktree 方法把 Git 检出作为 Herdr 工作区管理。`worktree.create` 创建检出,并返回新的 `workspace`、`tab`、`root_pane` 和 `worktree` 记录。请求的分支已在本地存在时检出它;否则从请求的 base 或 `HEAD` 创建分支。`worktree.open` 打开已有检出,或返回已打开的工作区。`worktree.remove` 对关联的子工作区运行 `git worktree remove`,从不删除分支。 - -从来源工作区创建 worktree: - -```json -{"id":"req_1","method":"worktree.create","params":{"workspace_id":"w1","branch":"worktree/api","focus":false}} -``` - -打开已有检出: - -```json -{"id":"req_2","method":"worktree.open","params":{"workspace_id":"w1","branch":"worktree/api","focus":true}} -``` - -移除关联的检出: - -```json -{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}} -``` - -`worktree.list`、`worktree.create` 和 `worktree.open` 中,`workspace_id` 和 `cwd` 最多用一个;两个都省略则使用活动工作区。`worktree.open` 中,`path` 和 `branch` 恰好用一个。原始 socket 的 `cwd` 和 `path` 值必须是绝对路径;CLI 在发送请求前会展开相对的 `--cwd` 和 `--path` 值。当工作区属于某个 Herdr worktree 组时,工作区响应包含可选的 `worktree` 来源信息。当已有工作区获得或改变 worktree 来源信息时,worktree 命令可能发出 `workspace.updated`。 - -Worktree 命令也发出生命周期事件。`worktree.create` 发出 `workspace.created`、`tab.created`、`pane.created` 和 `worktree.created`。`worktree.open` 发出 `worktree.opened`,并在打开新的 Herdr 工作区时同时发出工作区/标签页/窗格创建事件。`worktree.remove` 发出 `worktree.removed`;如果关联的工作区仍然打开,还会发出 `workspace.closed`。 - -## 智能体视图查询 - -`agent.view.set` 为内置 Agents 视图设置一个临时的声明式投影。智能体信息或当前 -UI 上下文变化时,该投影会重新求值。它控制展开和折叠的侧边栏、移动端 Agents -列表、鼠标目标、编号聚焦以及上一个/下一个智能体的导航顺序。它不会改变 -`agent.list`、通知、检测或全局待处理计数。 - -下面的示例显示当前呈现的 Space 中的智能体,以及其他位置需要处理的智能体, -然后按待处理优先级和最近状态转换排序: - -```json -{ - "id": "view_set", - "method": "agent.view.set", - "params": { - "source": "plugin:example.agent-views", - "label": "focus", - "filter": { - "op": "any", - "filters": [ - { - "op": "eq", - "field": "workspace_id", - "value": {"context": "current_workspace_id"} - }, - { - "op": "in", - "field": "status", - "values": ["blocked", "done"] - } - ] - }, - "sort": [ - {"field": "attention", "order": "desc"}, - {"field": "state_change_seq", "order": "desc"} - ] - } -} -``` - -过滤节点的 `op` 可以是 `all`、`any`、`not`、`eq`、`in` 或 `exists`。内置 -过滤字段是 `status`、`workspace_id`、`tab_id`、`pane_id`、`agent`、`seen` -和 `state_change_seq`。要过滤插件上报的窗格元数据,使用 `{"token":"name"}` -作为字段。值可以是字符串、布尔值、无符号整数或上下文对象。上下文值包括 -`current_workspace_id` 和 `current_tab_id`,并且只能与对应的 ID 字段比较。 -有效 status 值为 `idle`、`working`、`blocked`、`done` 和 `unknown`;`done` -表示 idle 且尚未查看。 - -排序字段包括 `workspace_order`、`tab_order`、`pane_order`、`attention`、 -`status`、`agent`、`seen`、`state_change_seq` 或 `{"token":"name"}`。排序是 -稳定的,按声明顺序求值,并接受 `asc` 或 `desc`。缺失值排在存在值之后。省略 -`sort` 时,现有 `ui.agent_panel_sort` 策略继续生效。自定义排序会临时替换该 -策略,但不会重写配置。 - -`source` 标识所有者。插件使用 `plugin:<HERDR_PLUGIN_ID>`;当所属插件不存在 -或被禁用时,Herdr 会拒绝设置。其他调用方可以使用自己的非 `plugin:` source。 -设置成功会原子替换之前的视图。该视图会持续到被 clear、被替换、所属插件被 -disable、unlink 或 uninstall,或者服务器退出。需要持久行为的插件应把查询保存到 -`HERDR_PLUGIN_STATE_DIR`,并从 `[[startup]]` 钩子重新应用。 - -可以无条件 clear,也可以只在指定 source 仍拥有视图时 clear: - -```json -{"id":"view_clear","method":"agent.view.clear","params":{}} -{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}} -``` - -source 不匹配时,活动视图保持不变。set 和 clear 响应使用 -`type: "agent_view"`,并报告 `active`、`source` 和可选的 `label`。 - -## 插件 API - -插件 API 是面向可执行工作流工具的早期宿主面。插件是带 `herdr-plugin.toml` 清单的包。清单声明可分享的动作、事件钩子、终端窗格入口点和链接处理器。动作和窗格仅限清单声明;运行时动作注册和运行时 argv 窗格创建不在 v1 范围内。 - -安装和链接的插件跨重启持久化。在 `plugin.link`、`plugin.unlink`、`plugin.enable` 和 `plugin.disable` 时,Herdr 在 `session.json` 旁写入一个 `plugins.json` 注册表文件。Herdr 不在运行时,`herdr plugin install` CLI 也写同一个注册表,然后启动时自动加载。启动时,Herdr 从原始路径重新读取每个清单;文件缺失或无法解析时,条目会带着 `warnings` 字段保留,`plugin.list` 会将其展示出来。 - -事件钩子的 `on` 值在链接时会对照已知的 Herdr 事件名校验。无法识别的名称不算错误 — 链接仍会成功 — 但返回的插件信息会包含警告 (例如 `"unknown event 'worktree.craeted'"`)。检查 `plugin.link` 和 `plugin.list` 响应中的 `warnings` 字段。 - -链接本地插件清单: - -```json -{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/path/to/plugin","enabled":true}} -``` - -`plugin.link` 也接受可选的 `source` 元数据。CLI 从 GitHub 安装时使用它,让 `plugin.list` 能显示来源、请求的 ref、解析的 commit 和托管检出路径: - -```json -{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/managed/plugin/herdr-plugin.toml","enabled":true,"source":{"kind":"github","owner":"ogulcancelik","repo":"herdr-plugin-examples","subdir":"worktree-bootstrap","requested_ref":"main","resolved_commit":"abc123","managed_path":"/data/plugins/github/<managed-checkout>","installed_unix_ms":1780000000000}}} -``` - -路径可以是包含 `herdr-plugin.toml` 的插件目录,或直接指向清单的路径。清单结构如下: - -```toml -id = "example.worktree-bootstrap" -name = "Worktree Bootstrap" -version = "0.1.0" -min_herdr_version = "0.7.0" -description = "Prepare new worktrees" -platforms = ["linux", "macos", "windows"] - -[[build]] -command = ["bun", "install"] - -[[actions]] -id = "bootstrap" -title = "Bootstrap worktree" -contexts = ["workspace"] -command = ["bun", "run", "bootstrap.ts"] - -[[events]] -on = "worktree.created" -command = ["bun", "run", "bootstrap.ts"] - -[[panes]] -id = "board" -title = "Worktree board" -placement = "overlay" -command = ["bun", "run", "board.ts"] - -[[link_handlers]] -id = "github-issue" -title = "Open GitHub issue" -pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$" -action = "bootstrap" -``` - -`min_herdr_version` 是必填项。字段缺失、无效,或比运行中的 Herdr 二进制更新时,服务器拒绝链接插件。 - -在顶层用你的插件支持的操作系统标识 (`linux`、`macos`、`windows`) 声明 `platforms`。本地开发允许省略 `platforms` — `plugin.link` 会成功,但响应包含警告。单个构建命令、动作、事件钩子、窗格和链接处理器可以声明自己的 `platforms` 来覆盖插件级列表;省略时从插件继承。调用有效 platforms 不包含当前操作系统的动作或打开这样的窗格,会返回 `platform_unsupported` 错误。 - -列出、启用、禁用或取消链接插件: - -```json -{"id":"req_plugin_list","method":"plugin.list","params":{}} -{"id":"req_plugin_disable","method":"plugin.disable","params":{"plugin_id":"example.worktree-bootstrap"}} -{"id":"req_plugin_enable","method":"plugin.enable","params":{"plugin_id":"example.worktree-bootstrap"}} -{"id":"req_plugin_unlink","method":"plugin.unlink","params":{"plugin_id":"example.worktree-bootstrap"}} -``` - -动作从链接的清单解析。`plugin.action.list` 返回所有已安装插件的全部动作;传 `plugin_id` 过滤。 - -```json -{"id":"req_plugin_actions","method":"plugin.action.list","params":{}} -{"id":"req_plugin_actions_filtered","method":"plugin.action.list","params":{"plugin_id":"example.worktree-bootstrap"}} -``` - -`plugin.action.list` 返回应用插件级继承后每个动作的有效 `platforms`。 - -用限定 id 或裸动作 id 调用动作: - -```json -{"id":"req_plugin_invoke","method":"plugin.action.invoke","params":{"action_id":"example.worktree-bootstrap.bootstrap","context":{"invocation_source":"keybinding"}}} -``` - -`plugin.action.invoke` 解析清单动作,启动清单命令,并返回 Herdr 构建的调用上下文和已启动命令的日志记录。缺失的上下文字段会从活动工作区、标签页、聚焦窗格、worktree 来源信息和请求 id 补全。调用被禁用插件的动作返回 `plugin_disabled` 错误。 - -Herdr 注入 `HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV=1`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_CONTEXT_JSON`,以及可用的 `HERDR_WORKSPACE_ID`、`HERDR_TAB_ID` 和 `HERDR_PANE_ID` 值。动作命令还收到 `HERDR_PLUGIN_ACTION_ID`;事件钩子收到 `HERDR_PLUGIN_EVENT` 和 `HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。 - -列出最近的动作和事件命令日志: - -```json -{"id":"req_plugin_logs","method":"plugin.log.list","params":{"plugin_id":"example.worktree-bootstrap","limit":20}} -``` - -当 Herdr 发出匹配的事件名 (比如 `worktree.created`) 时,事件钩子为已启用的已安装插件运行。 - -v1 没有 Herdr 管理的插件存储 API。`HERDR_PLUGIN_CONFIG_DIR` 和 `HERDR_PLUGIN_STATE_DIR` 只提供路径发现;文件、schema、迁移和清理归插件所有。 - -打开托管终端 UI: - -```json -{"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDR_ROLE":"board"},"focus":true}} -``` - -`plugin.pane.open` 要求已安装、已启用、平台兼容的插件,然后把请求的清单 `[[panes]]` 入口点作为 argv 支撑的终端窗格启动。清单窗格的 `placement` 默认为 `overlay`;请求的 `placement` 可以用 `overlay`、`popup`、`split`、`tab` 或 `zoomed` 覆盖清单。overlay 和 popup 使用活动平铺窗格作为启动上下文。弹窗终端是会话级模态界面,不会改变标签页布局;可选的 `width` 和 `height` 以终端单元格数或 `"80%"` 这样的百分比设置外层尺寸。省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗没有窗格 id,不属于任何 `pane.*` 或智能体 API,不会发出窗格生命周期事件,会把插件焦点上下文保留在底层平铺窗格上,也不会向其进程导出 `HERDR_PANE_ID`。弹窗启动返回 `ok`;`popup.close` 关闭活动弹窗,没有弹窗时返回 `popup_not_open`。split 和 zoomed 针对已有窗格,tab 可以针对工作区。split、tab、zoomed 和 overlay 打开后表现得像普通 Herdr 窗格,`plugin.pane.focus` 和 `plugin.pane.close` 仍可操作这些窗格。 - -## Socket 传输 - -Herdr 在本地 socket 上使用换行分隔的 JSON。在 Unix 上,那个 socket 是 Unix 域 socket。在 Windows 上,是命名管道。 - -每行发送一个请求: - -```json -{"id":"req_1","method":"ping","params":{}} -``` - -成功响应包含相同的 `id`: - -```json -{"id":"req_1","result":{"type":"pong"}} -``` - -事件订阅在初始响应之后保持连接打开。 - -## Socket 路径 - -默认 socket 位于你的 Herdr 配置目录下。 - -命名会话有各自独立的 socket: - -```text -~/.config/herdr/herdr.sock -~/.config/herdr/sessions/<name>/herdr.sock -``` - -解析顺序: - -1. 显式的 CLI `--session <name>` -2. `HERDR_SOCKET_PATH` -3. `HERDR_SESSION=<name>` -4. 默认会话 socket - -`HERDR_SOCKET_PATH` 只用于底层覆盖。 - -对插件来说,需要可移植的 Windows 行为时,优先调用 `HERDR_BIN_PATH` 和 CLI 包装命令。原始 socket 客户端要自己负责使用平台原生的本地 socket 形式。 - -## 智能体状态上报 - -集成用 `pane.report_agent` 上报智能体状态。 - -```json -{ - "id": "req_1", - "method": "pane.report_agent", - "params": { - "pane_id": "w1:p1", - "source": "custom:docs", - "agent": "docs-bot", - "state": "working", - "message": "building docs" - } -} -``` - -`state` 是语义性的。它影响等待、通知和汇总。只影响展示的值应通过元数据单独上报。 - -仅提供会话的官方集成用 `pane.report_agent_session` 上报原生会话引用。上报状态的集成仍然可以在 `pane.report_agent` 中包含原生会话引用。与状态无关的会话上报不影响等待、通知或汇总。 - -```json -{ - "id": "req_2", - "method": "pane.report_agent_session", - "params": { - "pane_id": "w1:p1", - "source": "herdr:codex", - "agent": "codex", - "agent_session_id": "..." - } -} -``` - -Herdr 存有原生会话引用时,`pane.get`、`pane.list`、`agent.get` 和 `agent.list` 暴露一个只读的 `agent_session` 对象: - -```json -{ - "agent_session": { - "source": "herdr:codex", - "agent": "codex", - "kind": "id", - "value": "..." - } -} -``` - -没有存储原生会话引用时,该字段被省略。 - -当 Herdr 能解析当前控制窗格 PTY 的进程的 cwd 时,`pane.get`、`pane.list`、`agent.get` 和 `agent.list` 也暴露 `foreground_cwd`。已有的 `cwd` 字段仍然是用于标签、follow-cwd 行为和恢复会话状态的窗格/工作区 cwd。 - -`PaneInfo` 和 `AgentInfo` 暴露可选的 `terminal_title` 和 `terminal_title_stripped` 字段。`terminal_title` 是经过安全规范化的最新 OSC 0/2 标题。`terminal_title_stripped` 会移除开头一个已识别的活动或旋转指示符字形及其后的空白。这些值归服务器所有,冷重启后不会保留,并且独立于元数据 `title` 和语义智能体状态。 - -当用户钩子想自定义展示、又不从 Herdr 集成接管生命周期状态时,使用 `pane.report_metadata`。 - -```json -{ - "id": "req_2", - "method": "pane.report_metadata", - "params": { - "pane_id": "w1:p1", - "source": "user:claude-title", - "agent": "claude", - "title": "Refactor auth middleware", - "display_agent": "Claude: auth", - "state_labels": { - "working": "refactoring auth", - "idle": "ready", - "done": "review ready" - }, - "tokens": { - "summary": "refactor auth", - "model": "opus" - }, - "ttl_ms": 3600000 - } -} -``` - -元数据上报只影响展示。有效的元数据可以覆盖窗格标题、显示的智能体名称、可见的状态标签和任意命名令牌。`working`、`blocked`、`idle`、等待、通知和汇总仍来自语义状态。原生会话恢复来自存储的官方会话引用。`agent` 是展示字段针对权威智能体标签的可选守卫;`applies_to_source` 同样保护展示字段,使其只适用于活动生命周期权威来源。这些守卫不作用于令牌补丁;令牌上报方负责清除和刷新 TTL。用 `display_agent` 修改可见名称。`state_labels` 的键必须是 `idle`、`working`、`blocked`、`done` 或 `unknown`。 - -令牌映射是针对每个资源的补丁。字符串设置键,JSON `null` 清除键,未提及的键保持不变。最后接受的更新生效。可选 TTL 分别应用于该次上报更新的每个令牌键。窗格令牌会在 pane 和 agent 的 get/list 响应中公开,并可在智能体侧边栏行中写成 `$name`。单次上报最多可包含 16 个令牌键,每个窗格或工作区最多保留 32 个键。令牌名称必须由 1–32 个 ASCII 字母、数字、下划线或连字符组成。 - -工作区令牌使用相同约定: - -```json -{"id":"req_3","method":"workspace.report_metadata","params":{"workspace_id":"w1","source":"user:jj","tokens":{"jj_status":"2 changes","old":null},"ttl_ms":5000}} -``` - -workspace 的 get/list 响应会公开生成的 `tokens` 映射,空间侧边栏行可显示 `$jj_status` 这类值。变更和 TTL 到期会发出包含最新工作区快照的 `workspace.metadata_updated`。该元数据事件会发送给 API 订阅者,但不会调用插件事件钩子。 - -展示文本在存储前被规范化。Herdr 去掉首尾空白、移除控制字符,并把 `title`、`display_agent`、每个状态标签和令牌值截断到 80 个字符。规范化后为空的令牌值会清除该键。 - -`source` 和 `applies_to_source` 是来源标识符。它们必须不超过 80 个字符,且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。 - -短期元数据用 `ttl_ms`。取值必须在 `1` 到 `86400000` 毫秒之间。想让元数据保留到被替换、清除或窗格或工作区关闭时,省略 `ttl_ms`。展示字段继续按来源过期;该次调用更新的每个令牌都有独立期限。令牌元数据不会在服务器重启后恢复。 - -钩子可能乱序发送更新时,使用 `seq`。对同一 `source`,序号小于等于最后接受序号的上报会被 API 接受,但被窗格状态忽略。每个窗格或工作区在其生命周期内最多接受来自 32 个不同来源的带序号令牌上报;清除或过期不会释放这些来源名额。 - -## 事件订阅 - -需要长期数据流时订阅事件: - -```json -{ - "id": "sub_1", - "method": "events.subscribe", - "params": { - "subscriptions": [ - { "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" } - ] - } -} -``` - -第一个响应确认订阅。之后的行是推送的事件。 - -工作区事件订阅包括 `workspace.created`、`workspace.updated`、`workspace.metadata_updated`、`workspace.renamed`、`workspace.moved`、`workspace.closed` 和 `workspace.focused`。`workspace.metadata_updated` 报告令牌变更和 TTL 到期,但不会调用插件事件钩子。其他工作区事件描述 Herdr UI/运行时的生命周期。当工作区属于 worktree 组时,`workspace.created` 包含可选的 `workspace.worktree` 来源信息。`workspace.moved` 包含被移动的 `workspace_id`、请求的 `insert_index` 和更新后的有序 `workspaces` 列表。在移除前 Herdr 仍能识别时,`workspace.closed` 包含最终的 `workspace` 快照。 -标签页事件订阅包括 `tab.created`、`tab.closed`、`tab.focused`、`tab.renamed` 和 `tab.moved`。`tab.moved` 包含被移动的 `tab_id`、`workspace_id`、请求的 `insert_index` 和该工作区更新后的有序 `tabs` 列表。 -窗格事件订阅包括 `pane.created`、`pane.updated`、`pane.closed`、`pane.focused`、`pane.moved`、`pane.exited`、`pane.agent_detected`、`pane.output_matched`、`pane.agent_status_changed` 和 `pane.scroll_changed`。终端标题变化可能发出 `pane.updated`,但如果原始标题只有旋转指示符发生变化且 `terminal_title_stripped` 不变,则不会发出。`pane.scroll_changed` 只针对一个 `pane_id`,每当 Herdr 观察到滚动快照变化时,都会发出 `pane_id`、`workspace_id` 和当前 `scroll` 指标。 -布局事件订阅包括 `layout.updated`。该事件携带一个标签页更新后的 `PaneLayoutSnapshot`。使用 `session.snapshot` 引导的客户端应替换具有相同 `workspace_id` 和 `tab_id` 的缓存布局。 - -Worktree 事件订阅包括 `worktree.created`、`worktree.opened` 和 `worktree.removed`。Worktree 事件描述 Git 检出的生命周期。`worktree.created` 包含打开的 `workspace` 和创建的 `worktree`。`worktree.opened` 包含目标 `workspace`、打开的 `worktree` 和 `already_open`。`worktree.removed` 包含 `workspace_id`、被移除的 `worktree` 和 `forced`。 - -生命周期事件用 `events.subscribe`。支持一次性等待时,专门的等待辅助命令会单独在文档中说明。 - -## 读取窗格 - -除非你在编写协议客户端,否则通过 CLI 使用 `pane.read`。 - -```bash -herdr pane read w1:p1 --source visible --lines 80 -herdr pane read w1:p1 --source recent --lines 120 -herdr pane read w1:p1 --source recent-unwrapped --lines 120 -herdr pane read w1:p1 --source detection -``` - -`recent-unwrapped` 对日志很有用,因为它忽略软折行。 -`detection` 返回智能体屏幕检测使用的底部缓冲区快照。 - -## 等待状态 - -用等待来协调智能体和脚本。 - -```bash -herdr agent wait w1:p1 --until done -herdr agent wait w1:p1 --until blocked -``` - -智能体等待观察的是语义状态,不是任意命令的完成。 - -## 响应结构 - -成功响应长这样: - -```json -{ - "id": "req_1", - "result": { - "type": "pane_info", - "pane": { - "pane_id": "w1:p1", - "terminal_id": "term_abc123", - "workspace_id": "w1", - "tab_id": "w1:t1", - "focused": true, - "agent_status": "working", - "revision": 42 - } - } -} -``` - -`server.agent_manifests` 返回生效的智能体检测清单来源和远程更新诊断信息,不重载规则: - -```json -{ - "id": "req_1", - "result": { - "type": "agent_manifest_status", - "last_check_unix": 1781043522, - "last_result": "checked", - "manifests": [ - { - "agent": "cursor", - "source": "/home/me/.config/herdr/agent-detection/cursor.toml", - "source_kind": "local override", - "active_version": "2026.06.10.1", - "cached_remote_version": "2026.06.10.1", - "local_override_shadowing_remote": true, - "remote_update_result": "current" - } - ] - } -} -``` - -`last_check_unix`、`last_result`、`active_version`、`cached_remote_version`、`remote_update_result`、`remote_update_error`、`remote_last_checked_unix` 和 `warning` 这类字段在不可用时被省略。`server.reload_agent_manifests` 在重载内存中的规则缓存后,返回带相同 `manifests` 条目结构的 `agent_manifest_reload`。 - -`agent.explain` 使用服务器生效的清单缓存,在运行中的服务器上评估目标窗格的检测快照: - -```json -{ - "id": "req_2", - "method": "agent.explain", - "params": { "target": "w1:p1" } -} -``` - -响应包含与 `herdr agent explain --json` 打印的相同的 explain 对象,包括最终状态、清单来源和版本、匹配的规则、已评估规则的证据、跳过状态原因、idle 回退原因,以及当完整生命周期钩子权威使屏幕规则不再权威时的 `screen_detection_skip_reason`。 - -客户端需要一个支持 `agent.explain` 的运行中服务器;升级 Herdr 后,请先重启或实时交接服务器,再依赖此方法。 - -错误长这样: - -```json -{ - "id": "req_1", - "error": { - "code": "not_found", - "message": "pane not found" - } -} -``` - -## 协议稳定性 - -Herdr 有一个用于客户端/服务器兼容性的协议版本。协议变更会在考虑发布兼容性的前提下进行评审。 - -在依赖新行为之前,用 `ping` 或 `herdr status` 检查服务器协议。对未知字段做宽容处理。 diff --git a/website/src/content/docs/zh-cn/troubleshooting.mdx b/website/src/content/docs/zh-cn/troubleshooting.mdx deleted file mode 100644 index 3560dd3d..00000000 --- a/website/src/content/docs/zh-cn/troubleshooting.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: 故障排除 -description: 诊断常见的安装、终端输入、会话、快捷键和远程连接问题。 ---- - -先检查版本和会话状态: - -```bash -herdr -V -herdr status -``` - -同时记录操作系统、外层终端名称和版本、会话是本地还是远程，以及是否使用了 tmux。 - -## Windows 上的 CJK 输入法窗口位置错误或光标闪烁 - -Herdr 在原生 Windows 和 WSL 上默认使用单元格绘制光标,因为 ConPTY 多路复用器重绘屏幕时,原生光标可能闪烁、跳动或显示旧位置。单元格绘制光标无法提供韩语、日语和中文输入法预编辑文本及候选窗口所需的原生光标定位。 - -如果输入法预编辑文本或候选窗口出现在错误位置,请启用原生光标: - -```toml -[ui] -host_cursor = "native" -``` - -原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标移动异常。要恢复视觉稳定的光标,请设置 `host_cursor = "drawn"`,或删除该设置以使用 Windows 默认值。当前限制详见 [Windows 测试版](/zh-cn/docs/windows-beta/)。 - -## Enter、Tab 或 Backspace 触发两次 - -旧版终端在应用启用 Kitty 键盘事件报告后，可能把 Enter、Tab 和 Backspace 的释放事件发送为与按下事件相同的字节。终端发送后，Herdr 无法区分这些重复字节。 - -请把外层终端更新到包含上游修复的版本: - -| 终端 | 最低修复版本 | -| --- | --- | -| kitty | 0.33.0 | -| foot | 1.20.0 | -| Alacritty | 0.15.0 | - -长期支持版 Linux 发行版中的旧终端软件包尤其容易出现此问题。已确认的边界捕获和上游链接见 [Herdr issue #1116](https://github.com/herdrdev/herdr/issues/1116)。如果当前版本仍有问题，请报告准确的终端版本，以及该问题是否也会在 Herdr 外出现。 - -## 按 Option+Left 或 Option+Right 时输入 `;3D` 或 `;3C` - -终端通常把 Alt+Left 和 Alt+Right 发送为标准的带修饰键方向键序列 `ESC[1;3D` 和 `ESC[1;3C`。在 macOS 上，需要先把外层终端配置为将 Option 视为 Alt。如果 shell 没有绑定这些序列，zsh 可能会把剩余字符显示为 `;3D` 或 `;3C`。kitty、Alacritty 和其他终端都可能出现这种情况；Herdr 和 tmux 都会保留原始的带修饰键方向键输入。 - -如果希望带修饰键的方向键在所有终端和嵌套 shell 中都执行按单词移动，请添加明确的 zsh 绑定: - -```zsh -bindkey $'\e[1;3D' backward-word -bindkey $'\e[1;3C' forward-word -``` - -kitty 在 Herdr 外可能表现不同，因为它的自动 zsh 集成只会为 kitty 直接启动的 shell 添加这些绑定，而不会为终端多路复用器创建的 shell 添加。请按照 kitty 的[手动 shell 集成说明](https://sw.kovidgoyal.net/kitty/shell-integration/#manual-shell-integration)，或在按键到达 shell 前通过 `kitty.conf` 映射它们: - -```text -map alt+left send_text all \x1bb -map alt+right send_text all \x1bf -``` - -终端应用可能会直接使用 Alt+Left 和 Alt+Right，因此 Herdr 不会改写带修饰键的方向键。调查详情见 [Herdr issue #1370](https://github.com/herdrdev/herdr/issues/1370)。 - -## Herdr 已更新，但运行中的会话仍是旧版本 - -更新二进制文件不一定会替换已经运行且兼容的服务器。先检查 `herdr status`。要启动更新后的服务器，请停止会话并重新启动 Herdr: - -```bash -herdr server stop -herdr -``` - -停止服务器会结束窗格进程。命名会话使用 `herdr session stop <name>`。更新器、软件包管理器和实时移交行为见[安装 Herdr](/zh-cn/docs/install/#update)。 - -## 找不到 `herdr` 命令 - -重启终端以重新加载环境，然后确认 Herdr 安装目录位于 `PATH` 中。通过软件包管理器安装的 Herdr 必须通过该管理器更新并加入环境。见[安装 Herdr](/zh-cn/docs/install/#verify)。 - -## 直接快捷键没有反应 - -操作系统或外层终端可能在 Herdr 收到按键前就拦截了组合键。请在对应层释放该组合键，或改用其他绑定。已知冲突和安全默认值见[键盘](/zh-cn/docs/keyboard/#going-prefix-free)。 - -## 远程连接无法认证 - -先用 `ssh <host>` 确认普通 OpenSSH 连接正常。若在非交互 shell、CI 或移动终端中使用带密码的密钥，请在远程连接前把密钥载入 `ssh-agent`。见[持久化和远程访问](/zh-cn/docs/persistence-remote/#remote-attach-over-ssh)。 - -## 查找诊断日志 - -Herdr 日志默认位于 `~/.config/herdr/`: - -```text -herdr.log -herdr-client.log -herdr-server.log -``` - -设置 `HERDR_LOG=herdr=debug` 可获得更多细节。报告问题时请附上当前日志和轮转后的日志。见[配置](/zh-cn/docs/configuration/#logs)。 diff --git a/website/src/content/docs/zh-cn/windows-beta.mdx b/website/src/content/docs/zh-cn/windows-beta.mdx deleted file mode 100644 index 5e922c3a..00000000 --- a/website/src/content/docs/zh-cn/windows-beta.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Windows 测试版 -description: Windows 原生支持的现状、受支持的工作流和已知限制。 ---- - -Windows 原生支持是实验性的测试版。 - -Windows 上的 Herdr 使用 ConPTY 和 Windows 的进程/运行时行为,而不是 Herdr 最初围绕构建的 Unix PTY 模型。有些 Herdr 功能可以干净地映射到 Windows,有些则不行。这个预览并不承诺每个 Linux/macOS 功能都会在 Windows 上得到完整支持。 - -测试版的目标是从真实使用中学习: 安装成功率、窗格可靠性、智能体工作流、bug 数量、缺失的功能,以及 Windows 用户是否从 Herdr 获得了足够的价值。基于这些反馈,Windows 支持可能升级为稳定版,可能在成熟前保持仅预览,也可能在维护成本不合理时被缩减。 - -用 PowerShell 安装 Windows 原生测试版构建: - -```powershell -powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex" -``` - -Windows 测试版构建只通过预览通道发布。在 Windows 上,Herdr 默认使用预览通道,且不会修改你的配置。安装器将发布版本保存在 `%USERPROFILE%\.herdr\packages\standalone\releases` 下,让 `%LOCALAPPDATA%\Programs\Herdr\bin` 指向当前版本,并保留少量旧版本,以免运行中的进程阻塞更新。 - -对于内部测试,`HERDR_MANIFEST_URL` 可以让安装器指向自定义清单,而不是 Herdr 的稳定或预览清单。 - -## 测试版支持 - -| 能力 | 状态 | -| --- | --- | -| 本地持久会话 | 测试版 | -| 通过 ConPTY 的原生窗格 | 测试版 | -| Windows Terminal / PowerShell 应用连接 | 测试版 | -| `cmd.exe` 窗格 | 测试版 | -| 启动 cwd 和工作区标签 | 测试版 | -| 窗格启动 cwd | 测试版 | -| 智能体命令发现 | 测试版 | -| 智能体自报告集成 | 测试版 | -| 智能体进程树检测 | 测试版 | -| 从已知 cwd 检测 Git/worktree | 测试版 | -| 插件 | 预览 | -| 窗格屏幕历史 | 测试版 | -| 嵌套启动覆盖 | 测试版 | - -Windows 智能体进程检测会扫描窗格 shell 的后代进程,识别直接运行的智能体和常见的命令包装器。它对 Codex、Claude 等智能体很有用,但和 Unix 前台进程组检测不是一回事。 - -插件以预览状态支持在清单中声明 `windows` 平台。GitHub 安装、本地链接、构建命令、动作、事件和插件窗格在 Windows 上尽力而为。命令是 argv 命令,必须兼容 Windows;`npm`、`bun`、`node` 之类的 Node 包 shim 只要在 `PATH` 上就应该能用,而使用 `sh` 或 Bash 的 Unix 专用示例需要 Windows 专用的替代方案。平台过滤器会跳过不支持的构建命令,并对不支持的动作或窗格返回 `platform_unsupported`。 - -## 部分支持 - -| 能力 | 状态 | -| --- | --- | -| shell `cd` 之后的实时 cwd | 部分支持 | -| 通过 shell 集成/OSC7 的实时 cwd | 测试版 | -| 向智能体粘贴剪贴板图像 | 未验证 | -| CJK 输入法候选窗口定位 | 部分支持 | -| Kitty graphics 渲染 | 未验证 | -| 主机光标渲染 | 部分支持 | - -Herdr 可以在正确的目录中启动窗格,并能从你启动 Herdr 的目录创建初始工作区。启动之后 PowerShell 的目录变化则不同: Herdr 能检查的进程字段无法可靠跟踪后续的逻辑 `cd` 变化。实时 cwd 上报请使用 Herdr 集成或提示符 shell 集成。 - -Windows Terminal 可能为特定智能体支持图像粘贴路径,但 Herdr 自己的剪贴板图像读取器尚未在 Windows 上接通。在 Windows 剪贴板桥实现并测试之前,请把 `alt+v` 图像粘贴视为未验证。远程剪贴板图像桥是独立功能,仍然绑定于 Unix/macOS 的 `herdr --remote`。 - -Kitty graphics 仍是实验性功能,尚未宣称支持 Windows。除非你专门在 Windows Terminal 中测试图像渲染,否则保持 `experimental.kitty_graphics = false`。 - -## 已知注意事项 - -### 光标渲染 - -Herdr 的原生 Windows 窗格依赖 ConPTY。当前 Windows 终端的光标处理可能会在多路复用器重绘屏幕时显示中间光标位置。因此,在持续输出期间,原生光标可能闪烁、跳动,或短暂留在旧位置。这个现象也能在其他 Windows 原生终端多路复用器以及直接连续更新 VT 光标位置的压力测试中复现,所以 Herdr 无法在保留原生光标行为的同时彻底消除它。 - -为了优先保证视觉稳定性,默认的 `host_cursor = "auto"` 会在原生 Windows 和 WSL 上把 Herdr 光标绘制为终端单元格内容。其他 Linux 和 macOS 客户端仍使用原生终端光标。Windows 上的绘制光标稳定且不闪烁,但不会使用外层终端的原生闪烁、形状或光标颜色。 - -绘制光标并不是 Windows 用来定位输入法预编辑文本和候选窗口的真实光标。因此,韩语、日语或中文输入法 UI 可能显示在错误位置。如果遇到这个问题,请改用外层终端光标: - -```toml -[ui] -host_cursor = "native" -``` - -原生模式会恢复输入法定位,但在持续输出期间可能再次出现偶发的光标闪烁、跳动或旧位置残影。这是当前 Windows 测试版中的兼容性取舍。 - -### 键盘和鼠标 - -Windows 终端并不都以相同形式报告带修饰键的按键。Herdr 在 Windows Terminal 和 Windows 上的 Alacritty 中保留鼠标报告和 `ctrl+j`,但 `shift+enter` 只有在外层终端把它报告为独立的修饰 Enter 键时才有效。如果 Windows 或终端把它报告为普通 Enter,Herdr 会转发普通 Enter。 - -## 复制与粘贴 - -Herdr 的窗格文本复制在 Windows 测试版上可用。在窗格内拖选文本即可通过 Herdr 复制。 - -文本粘贴请在 Windows Terminal 中使用 `ctrl+shift+v`。多行文本粘贴是带括号的 (bracketed),因此 shell 和智能体提示符会把它作为一次粘贴接收,而不是逐行提交。按住 `shift` 再右键,可以使用外层终端的粘贴操作,而不把点击发给 Herdr。 - -## Windows 测试版不支持 - -| 能力 | 状态 | -| --- | --- | -| 直接终端附加 | 不支持 | -| Windows 二进制的 `herdr --remote` | 不支持 | -| 实时服务器交接 | 不支持 | -| Unix 文件描述符交接 | 不支持 | -| Unix 前台进程组 | 不支持 | -| 远程剪贴板图像桥 | 不支持 | -| 前缀输入法切换 | 不支持 | -| 签名二进制 / 规避 SmartScreen | 不支持 | - -在 Windows 上进行远程工作,请 SSH 到服务器并在那里运行 `herdr`: - -```powershell -ssh you@server -herdr -``` - -这种模式下 Herdr 运行在远程主机上。Windows 原生的 `herdr --remote` 不在测试版范围内。 - -Windows 更新通过 Windows 安装器进行,并更新带版本号的安装联接点。更新后请重启运行中的 Herdr 会话。实时交接仅限 Unix。 - -## 报告 Windows 测试版问题 - -请包含: - -- Herdr 版本。 -- Windows 版本。 -- 终端应用。 -- Shell,比如 PowerShell 或 cmd。 -- 是否使用了命名的 `HERDR_SESSION`。 -- 相关的 Herdr 日志。 -- 精确的复现步骤。 |