From bc064e9d034711ba40e4e42a0129934752f0b802 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Tue, 21 Jul 2026 21:01:27 +0300 Subject: docs: finalize release docs and refresh agent skill --- .../src/content/docs/zh-cn/agent-automation.mdx | 121 +++++++++++++++++++++ website/src/content/docs/zh-cn/agent-skill.mdx | 2 +- website/src/content/docs/zh-cn/agents.mdx | 24 +--- website/src/content/docs/zh-cn/cli-reference.mdx | 68 +++++++++--- website/src/content/docs/zh-cn/configuration.mdx | 16 ++- website/src/content/docs/zh-cn/integrations.mdx | 4 +- website/src/content/docs/zh-cn/plugins.mdx | 34 +++++- website/src/content/docs/zh-cn/session-state.mdx | 2 + website/src/content/docs/zh-cn/socket-api.mdx | 82 +++++++++++++- 9 files changed, 303 insertions(+), 50 deletions(-) create mode 100644 website/src/content/docs/zh-cn/agent-automation.mdx (limited to 'website/src/content/docs/zh-cn') diff --git a/website/src/content/docs/zh-cn/agent-automation.mdx b/website/src/content/docs/zh-cn/agent-automation.mdx new file mode 100644 index 00000000..7f6eeb58 --- /dev/null +++ b/website/src/content/docs/zh-cn/agent-automation.mdx @@ -0,0 +1,121 @@ +--- +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 的主机回滚缓冲区。如果回复超出可见窗格,`recent` 和 `recent-unwrapped` 无法恢复应用已不再显示的行;增大 `--lines` 也无法获取这些历史内容。字体较大或窗格较小时更容易遇到此限制。 + +可以要求智能体简洁回复、扩大窗格或使用较小字体,也可以使用智能体自身的记录和滚动控件。在智能体内部滚动后,使用 `--source visible` 读取它当前绘制的页面。 + +成功的 `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 index a7657053..f905f347 100644 --- a/website/src/content/docs/zh-cn/agent-skill.mdx +++ b/website/src/content/docs/zh-cn/agent-skill.mdx @@ -58,7 +58,7 @@ claude ## 面向智能体的参考 -完整的命令指南就在技能文件本身。它涵盖窗格 ID、`pane split`、`pane run`、`pane read`、`wait output`、`wait agent-status`、工作区和标签页命令,以及协作配方。 +完整的命令指南就在技能文件本身。它涵盖窗格 ID、`pane split`、`pane run`、`pane read`、`pane wait-output`、`agent wait`、工作区和标签页命令,以及协作配方。 在这里阅读源文件: diff --git a/website/src/content/docs/zh-cn/agents.mdx b/website/src/content/docs/zh-cn/agents.mdx index f169fbe1..fb478081 100644 --- a/website/src/content/docs/zh-cn/agents.mdx +++ b/website/src/content/docs/zh-cn/agents.mdx @@ -5,6 +5,8 @@ description: 了解 Herdr 能检测什么、智能体状态如何工作,以及 Herdr 为同时运行多个编程智能体而生。每个智能体都待在一个真实的终端窗格里,shell、日志、提示符和运行中的进程都完好无损。Herdr 跟踪哪些窗格里有智能体,把它们的状态汇总到标签页和工作区,让你直接跳到需要关注的窗格,而不是手动轮询每个终端。 +要从脚本或另一个智能体协调它们,请参阅[智能体自动化](/zh-cn/docs/agent-automation/)。 + ## 受支持的智能体 常见编程智能体开箱即用地支持自动检测。重要的区别不在于 Herdr 能不能看到某个智能体,而在于允许哪个信号来决定 `idle`、`working` 和 `blocked`。 @@ -47,7 +49,7 @@ Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI 和 Cursor Agent CL ## 虚拟机与沙箱包装器 -在 Linux 上,VM、Bubblewrap 或 `fence` 之类的包装器可能把真实的智能体进程从宿主的 `/proc` 中隐藏起来。在命令上设置 `HERDR_AGENT=`,例如 `HERDR_AGENT=claude fence -- claude`,告诉 Herdr 该使用哪个已有智能体的屏幕清单。这个提示的作用范围只限于那个前台进程;除非所有继承它的前台进程都应被视为该智能体,否则不要在 shell 里全局 export。 +在 Linux 和 macOS 上,宿主可见的包装器可能会向 Herdr 隐藏真实的智能体进程。在包装器命令上设置 `HERDR_AGENT=`,告诉 Herdr 应使用哪个已有智能体的屏幕清单。例如,在 Linux 上运行 `HERDR_AGENT=claude fence -- claude`,或在 macOS 上运行 `HERDR_AGENT=claude nono run --profile claude-code -- claude`。这个提示的作用范围只限于该前台进程;仅在 VM 或容器内部设置时 Herdr 无法看到它,而且除非所有继承的前台进程都应被视为该智能体,否则不要全局 export。 ## blocked 状态 @@ -110,7 +112,7 @@ herdr agent rename w1:p1 reviewer herdr agent rename reviewer --clear ``` -目标可以是终端 ID、唯一的智能体名称、检测到或上报的智能体标签,以及旧式窗格 ID。 +目标使用唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。 ## 自定义状态标签 @@ -131,24 +133,6 @@ herdr pane report-metadata w1:p1 \ 智能体侧边栏行也可以选择使用 `terminal_title` 或 `terminal_title_stripped`;两者都不在默认行中。前者显示经过安全规范化的最新 OSC 0/2 终端标题,后者会移除开头一个已识别的活动或旋转指示符字形及其后的空白。这些值由 Herdr 服务器所有,冷重启后不会保留,并且独立于元数据标题和语义智能体状态。因此,如果移除后的文本不变,旋转动画可以改变原始标题而不触发窗格更新。 -## 从 CLI 启动智能体 - -当你希望一个终端被当作智能体目标时,使用 `herdr agent ...` 命令。智能体目标会出现在 `agent list` 中,可以按智能体名称读取或发送输入,可以按智能体状态等待,也可以被直接附加。 - -从脚本向 Herdr 中启动一个智能体: - -```bash -herdr agent start reviewer --cwd ~/project --split right -- pi -``` - -也可以把该智能体放进特定的工作区或标签页: - -```bash -herdr agent start docs --workspace w1 --tab w1:t1 -- claude -``` - -普通终端、服务器、测试、shell 和底层终端输入请使用 `herdr pane ...` 命令。例如跑 `cargo test` 用 `pane split` 和 `pane run`,而不是 `agent start`,除非那个终端就是有意要当作智能体目标。 - ## 直接附加到智能体 把当前终端附加到某一个智能体终端,而不是完整的 Herdr UI: diff --git a/website/src/content/docs/zh-cn/cli-reference.mdx b/website/src/content/docs/zh-cn/cli-reference.mdx index 6275adb7..03831dc7 100644 --- a/website/src/content/docs/zh-cn/cli-reference.mdx +++ b/website/src/content/docs/zh-cn/cli-reference.mdx @@ -126,6 +126,8 @@ herdr workspace close 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 @@ -150,6 +152,10 @@ herdr tab rename