docs: finalize release docs and refresh agent skill

9 files changed, 303 insertions, 50 deletions

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=<agent>`,例如 `HERDR_AGENT=claude fence -- claude`,告诉 Herdr 该使用哪个已有智能体的屏幕清单。这个提示的作用范围只限于那个前台进程;除非所有继承它的前台进程都应被视为该智能体,否则不要在 shell 里全局 export。
+在 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 状态
 
@@ -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 <workspace_id>
 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 <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
@@ -173,14 +179,20 @@ herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--f
 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]
+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
@@ -191,7 +203,9 @@ 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` 的别名被接受。
 
-`pane run` 把文本和回车作为一个原子操作提交。发送命令时优先用它,而不是 `send-text` 加 `send-keys Enter`。
+标准拼写是 `esc`;也接受 `escape`。
+
+`pane run` 会遵循当前的 bracketed paste 模式,并把文本和 Enter 作为一个原子操作提交。发送命令时优先用它,而不是 `send-text` 加 `send-keys Enter`;单独的发送操作仍是底层操作,不会提交命令。
 
 从自定义钩子上报智能体状态:
 
@@ -204,8 +218,23 @@ herdr pane report-agent <pane_id> \
   [--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。
@@ -237,23 +266,34 @@ herdr pane report-metadata <pane_id> \
 
 ## 智能体
 
+窗格与智能体的模型和完整协调示例见[智能体自动化](/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 <target> <text>
+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> --status <idle|working|blocked|unknown> [--timeout MS]
+herdr agent wait <target> [--until STATUS]... [--timeout MS]
 herdr agent attach <target> [--takeover]
-herdr agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
+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。名称和标签是智能体的身份。终端 ID 和旧式窗格 ID 是底层的逃生舱。
+智能体目标只能是唯一的实时智能体名称,或当前承载该智能体的窗格 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 或被替换时清除;短暂的检测不确定不会清除它。
 
-`agent read` 读取解析出的终端流。`agent send` 向该流写入字面文本。`agent get`、`agent focus`、`agent wait` 和 `agent attach` 要求解析出的终端具有智能体身份。`agent rename` 可以赋予这个身份。
+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`。
 
@@ -270,21 +310,19 @@ herdr terminal title clear
 从直接附加中用 `ctrl+b q` 分离。用 `ctrl+b ctrl+b` 发送字面的 `ctrl+b`。
 `terminal title clear` 恢复 Herdr 默认的外层终端窗口标题。
 
-## 等待
+## 输出等待
 
 等待窗格中的输出:
 
 ```bash
-herdr wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]
+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`。
 
-```bash
-herdr wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]
-```
+`pane wait-output` 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 `recent`;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。`--lines` 可以修改这个行数限制。`--match` 在单行中查找字面子串;`--regex` 使用 Rust 正则表达式语法并逐行匹配。
 
-普通命令和服务器用 `wait output`。编程智能体用 `wait agent-status`。
+`pane wait-output`、`agent wait` 和 `agent prompt --wait` 在省略 `--timeout` 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。
 
 ## 集成
 
@@ -389,6 +427,8 @@ herdr plugin pane close <pane_id>
 | `recent-unwrapped` | 不带软折行的最近回滚内容。最适合日志。 |
 | `detection` | 智能体屏幕检测使用的底部缓冲区快照。 |
 
+此表描述读取时的含义。仅对 `pane wait-output` 而言,`recent` 和 `recent-unwrapped` 都搜索 recent 的未折行快照,默认写法仍是 `recent`。
+
 ## 环境变量
 
 | 变量 | 用途 |
diff --git a/website/src/content/docs/zh-cn/configuration.mdx b/website/src/content/docs/zh-cn/configuration.mdx
index 055ca3ad..bb04da07 100644
--- a/website/src/content/docs/zh-cn/configuration.mdx
+++ b/website/src/content/docs/zh-cn/configuration.mdx
@@ -295,6 +295,18 @@ Space 行支持以下内置 token：
 
 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 布局：
@@ -334,7 +346,9 @@ herdr pane report-metadata <pane_id> \
   --token summary="reviewing authentication"
 ```
 
-自定义 Space token 可用同样的方式通过 `herdr workspace report-metadata` 报告。未报告的自定义 token 会直接消失。元数据报告方只提供值，不能选择行或样式。有关清除、顺序和过期值的信息，请参阅 [CLI 参考：报告元数据](/docs/cli-reference/#panes)。
+自定义 Space token 可用同样的方式通过 `herdr workspace report-metadata` 报告。未报告的自定义 token 会直接消失。
+
+元数据上报方只提供值；样式由本地侧边栏配置控制。有关限制、清除、顺序和过期值的信息，请参阅 [CLI 参考：报告元数据](/docs/cli-reference/#panes)。
 
 侧边栏行设置仅影响展开的桌面侧边栏。折叠视图和移动视图仍使用紧凑布局。
 
diff --git a/website/src/content/docs/zh-cn/integrations.mdx b/website/src/content/docs/zh-cn/integrations.mdx
index 2e494e12..c49f61db 100644
--- a/website/src/content/docs/zh-cn/integrations.mdx
+++ b/website/src/content/docs/zh-cn/integrations.mdx
@@ -76,7 +76,7 @@ Herdr 把内置扩展写入:
 ~/.pi/agent/extensions/herdr-agent-state.ts
 ```
 
-如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts`。extensions 目录必须已经存在。卸载只删除那个扩展文件。
+如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts`。如果 Pi agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。
 
 ## OMP
 
@@ -92,7 +92,7 @@ Herdr 把内置扩展写入:
 ~/.omp/agent/extensions/herdr-omp-agent-state.ts
 ```
 
-如果设置了 `PI_CODING_AGENT_DIR`,Herdr 会改为写入 `$PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts`。extensions 目录必须已经存在。卸载只删除那个扩展文件。
+如果设置了 `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 窗格。
 
diff --git a/website/src/content/docs/zh-cn/plugins.mdx b/website/src/content/docs/zh-cn/plugins.mdx
index a22e56b8..306bda53 100644
--- a/website/src/content/docs/zh-cn/plugins.mdx
+++ b/website/src/content/docs/zh-cn/plugins.mdx
@@ -62,6 +62,9 @@ command = ["npm", "ci"]
 command = ["npm", "run", "build"]
 platforms = ["linux", "macos"]
 
+[[startup]]
+command = ["node", "dist/restore.js"]
+
 [[actions]]
 id = "apply"
 title = "Apply layout"
@@ -97,9 +100,9 @@ ASCII 字母、数字、冒号、下划线和连字符,但不能用点。每种
 `plugin.id.action` 的形式。
 
 用 `platforms = ["linux", "macos", "windows"]` 声明插件可以运行的平台。
-构建命令、动作、事件钩子、窗格和链接处理器也可以声明自己的 `platforms`;
-条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地插件在链接
-时会给出警告。
+构建命令、启动钩子、动作、事件钩子、窗格和链接处理器也可以声明自己的
+`platforms`;条目级的 platforms 覆盖顶层列表。没有顶层 `platforms` 的本地
+插件在链接时会给出警告。
 
 `command` 的值是 argv 数组。Herdr 不会通过 shell 运行它们,所以除非你的
 命令自己启动 shell,否则没有 shell 展开。语言相关的行为放到你的脚本或
@@ -174,8 +177,12 @@ herdr plugin log list --plugin example.layout
 `plugin install` 只接受 GitHub 简写,比如 `owner/repo/subdir`。它用 `git`
 克隆,在交互式终端展示预览,运行受支持的构建命令,然后把检出保存到
 Herdr 管理的插件数据下并注册。非交互式安装用 `--yes`。重新安装 GitHub
-管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上;请先
-unlink 或 uninstall 本地插件。`plugin install` 和 `plugin link` 会创建
+管理的插件会替换该托管检出。已安装和已链接的插件及其启用状态对当前用户
+全局生效,可在所有 Herdr 会话中使用。即使 Herdr 服务器没有运行,也可以通过
+`plugin install` 和 `plugin link` 注册插件。仅安装在 Herdr 0.7.3 命名会话中的
+插件必须重新 install 或 link;现有的插件配置和状态会保留。
+不允许覆盖安装到本地链接的插件之上;请先 unlink 或 uninstall 本地插件。
+`plugin install` 和 `plugin link` 会创建
 插件的配置和状态目录,`plugin config-dir <id>` 打印配置目录,方便安装
 文档和 shell 脚本使用。
 
@@ -203,6 +210,20 @@ 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`、
@@ -210,7 +231,8 @@ Herdr socket 环境变量。插件作者应在文档中说明所需的系统工�
 `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_ACTION_ID`;启动钩子和事件钩子收到 `HERDR_PLUGIN_EVENT`
+（启动钩子中的值为 `startup`）,事件钩子还会收到
 `HERDR_PLUGIN_EVENT_JSON`;窗格命令收到 `HERDR_PLUGIN_ENTRYPOINT_ID`。
 
 `HERDR_PLUGIN_ROOT` 是已安装或已链接的插件目录。不要把用户凭据或持久
diff --git a/website/src/content/docs/zh-cn/session-state.mdx b/website/src/content/docs/zh-cn/session-state.mdx
index c87016ec..cf796d0c 100644
--- a/website/src/content/docs/zh-cn/session-state.mdx
+++ b/website/src/content/docs/zh-cn/session-state.mdx
@@ -93,6 +93,8 @@ Herdr 只会恢复那些通过当前官方 Herdr 集成上报了原生会话引�
 
 这与快照恢复、窗格历史回放和智能体原生会话恢复不同。交接尝试让当前进程活下去,其他路径则是在旧服务器已经停止之后重建状态。
 
+交接保护的是由服务器拥有的长期会话状态:窗格 PTY 和进程、智能体身份与持久元数据,以及替换服务器所需的插件/会话状态。它不会跨替换边界保留临时协调状态。进行中的 CLI 或 API 请求、等待、订阅流、客户端套接字和窗格间消息可能会中断;客户端应重新连接并重试。
+
 实时交接是实验性功能,需要主动开启:
 
 ```bash
diff --git a/website/src/content/docs/zh-cn/socket-api.mdx b/website/src/content/docs/zh-cn/socket-api.mdx
index 95f89be6..2077d571 100644
--- a/website/src/content/docs/zh-cn/socket-api.mdx
+++ b/website/src/content/docs/zh-cn/socket-api.mdx
@@ -36,7 +36,7 @@ socket API 可以:
 - 创建、列出、聚焦、重命名和关闭工作区
 - 创建、列出、聚焦、重命名和关闭标签页
 - 列出、检查、分割、交换、聚焦、调整、重命名、读取、关闭窗格并向其发送输入
-- 通过 CLI 辅助命令列出、检查、读取、发送、重命名、聚焦、启动和附加智能体
+- 通过 CLI 辅助命令列出、检查、读取、提示、等待、重命名、聚焦、启动和附加智能体
 - 从钩子和插件上报自定义智能体状态
 - 订阅事件并等待输出或状态变化
 - 安装和卸载内置集成
@@ -77,7 +77,7 @@ herdr pane split w1:p1 --direction right --ratio 0.333
 等待智能体:
 
 ```bash
-herdr wait agent-status w1:p1 --status done
+herdr agent wait w1:p1 --until done
 ```
 
 读取窗格输出:
@@ -102,12 +102,12 @@ herdr pane read w1:p2 --source recent --lines 50
 | 窗格 | `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`、`agent.rename`、`agent.focus`、`agent.start` |
+| 智能体 | `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` |
 
-一些 CLI 命令是这些方法的便捷包装。比如 `herdr agent wait` 先解析智能体目标,然后订阅窗格智能体状态事件。
+`agent.wait` 由服务器拥有并由事件驱动。它会固定到已解析的窗格占用者,因此替换后的智能体不能满足该等待。`agent.prompt` 接受可选的 `wait` 对象,其中包含 `until` 和 `timeout_ms`;这样可在一个请求中提交提示并开始等待,避免两个独立调用之间的竞态。
 
 `session.snapshot` 为维护本地运行时缓存的客户端返回一次性引导快照。响应包含版本/协议元数据、当前聚焦的工作区/标签页/窗格 id、工作区记录、标签页记录、窗格记录、标签页布局快照和智能体记录。它不是订阅;读取后应订阅资源事件,并根据事件更新本地缓存。重新连接后或本地缓存可能已过期时,再次调用 `session.snapshot`。工作区记录也包含关联 worktree 的来源信息。完整的仓库 worktree 发现仍使用 `worktree.list`。
 
@@ -297,6 +297,76 @@ Worktree 方法把 Git 检出作为 Herdr 工作区管理。`worktree.create` �
 
 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 范围内。
@@ -589,8 +659,8 @@ herdr pane read w1:p1 --source detection
 用等待来协调智能体和脚本。
 
 ```bash
-herdr wait agent-status w1:p1 --status done
-herdr wait agent-status w1:p1 --status blocked
+herdr agent wait w1:p1 --until done
+herdr agent wait w1:p1 --until blocked
 ```
 
 智能体等待观察的是语义状态,不是任意命令的完成。