docs: finalize next release documentation

1 files changed, 173 insertions, 256 deletions

diff --git a/website/src/content/docs/zh-cn/configuration.mdx b/website/src/content/docs/zh-cn/configuration.mdx
index ac9bc73c..055ca3ad 100644
--- a/website/src/content/docs/zh-cn/configuration.mdx
+++ b/website/src/content/docs/zh-cn/configuration.mdx
@@ -3,134 +3,117 @@ title: 配置
 description: 配置 Herdr 的按键绑定、主题、侧边栏行为、通知和高级选项。
 ---
 
-Herdr 无需配置文件即可工作。当你想要自定义按键、主题、侧边栏设置、通知或高级行为时再添加。
+Herdr 无需配置文件即可使用。当你想自定义按键、主题、侧边栏布局、通知或高级行为时，再添加配置文件。
 
-在找某个具体的键？[配置参考](/zh-cn/docs/config-reference/)列出了所有键的类型、默认值与允许的取值。
+在查找某项设置或按键绑定？请在[配置参考](/docs/config-reference/)中搜索，其中列出了每个键、类型、默认值和允许值。本页重点介绍设置方法、常用配置方案，以及需要比参考表格更详细说明的配置结构。
 
 ## 配置文件
 
-Herdr 从这里读取配置:
+Herdr 从以下位置读取配置：
 
 ```text
-Linux 和 macOS: ~/.config/herdr/config.toml
-Windows:         %APPDATA%\herdr\config.toml
+Linux and macOS: ~/.config/herdr/config.toml
+Windows:          %APPDATA%\herdr\config.toml
 ```
 
-运行 `herdr --help` 可查看系统解析后的配置文件路径。
+运行 `herdr --help` 可查看系统解析后的配置路径。
 
-打印完整的默认配置:
+打印完整的默认配置：
 
 ```bash
 herdr --default-config
 ```
 
-想要一个完整的起点,可以把它保存为你的配置:
+如果想从完整配置开始，可以将其保存为你的配置文件：
 
 ```bash
 herdr --default-config > ~/.config/herdr/config.toml
 ```
 
-如果某个配置值无效,Herdr 会回退到安全默认值,并在启动时显示警告。
+如果配置值无效，Herdr 会回退到安全的默认值，并显示启动警告。
 
-当 `onboarding` 缺失或为 true 时,Herdr 会显示首次运行引导。从引导继续会写入 `onboarding = false` 并打开设置的集成标签页。安装完成后想跳过该流程时可以设置它。
+当 `onboarding` 缺失或为 true 时，Herdr 会显示首次运行设置。继续完成引导会写入 `onboarding = false`，并打开设置中的集成标签页。完成设置后，如果想跳过此流程，请设置该值。
 
 ```toml
 onboarding = false
 ```
 
-## 更新
-
-Linux 和 macOS 的直接安装默认使用稳定更新通道。Windows 测试版安装默认使用预览通道,在稳定的 Windows 发布可用之前不能切换到稳定版。
-
-```toml
-[update]
-channel = "stable"
-version_check = true
-manifest_check = true
-```
-
-设置 `channel = "preview"` 让 `herdr update` 安装从当前开发分支手动发布的预览构建。Homebrew、mise 和 Nix 安装忽略预览通道,通过各自的包管理器更新。
-
-设置 `version_check = false` 禁用对新 Herdr 版本的后台检查。手动 `herdr update` 仍使用配置的通道。
-
-设置 `manifest_check = false` 禁用后台的远程智能体检测清单检查。Herdr 仍使用内置清单和本地覆盖。
-
 ## 重载配置
 
-编辑 `config.toml` 后重载运行中的服务器:
+编辑 `config.toml` 后，重载正在运行的服务器：
 
 ```bash
 herdr server reload-config
 ```
 
-也可以在 Herdr 中打开全局菜单并选择 `reload config`。
+你也可以打开 Herdr 的全局菜单并选择 `reload config`。
 
-重载会在不重启窗格的情况下应用大多数 UI 设置。仅启动时生效的设置仍需要重启。
+重载会在不重启窗格的情况下应用大多数 UI 设置。仅启动时生效的设置仍需重启。
 
 ## 终端默认值
 
-设置 Herdr 为新建交互式窗格使用的可执行文件:
+设置 Herdr 创建新交互式窗格时使用的可执行文件：
 
 ```toml
 [terminal]
 default_shell = "nu"
 ```
 
-未设置或为空时,Herdr 使用 `$SHELL`,然后是 `/bin/sh`。这是可执行文件名或路径,不是 shell 命令行。现有窗格在重建之前保持当前 shell。命令窗格仍通过 `/bin/sh -c` 运行;分离式自定义命令按键绑定使用 Herdr 已有的 `/bin/sh -lc` 路径。
+未设置或值为空时，Herdr 会依次使用 `$SHELL`、Unix 上的 `/bin/sh` 或 Windows 上的 PowerShell。该值是可执行文件名或路径，而不是 shell 命令行。现有窗格会保留当前 shell，直到重新创建。自定义命令按键绑定中的字符串在 Unix 上通过 `/bin/sh -c` 执行窗格命令，通过 `/bin/sh -lc` 执行分离式命令；在 Windows 上则通过 `cmd.exe /d /c` 执行。
 
-设置 Herdr 如何启动新建交互式窗格的 shell:
+设置 Herdr 如何启动新建交互式窗格的 shell：
 
 ```toml
 [terminal]
 shell_mode = "auto"
 ```
 
-`shell_mode = "auto"` 在 macOS 上启动登录 shell,使 `/usr/libexec/path_helper` 这类仅登录时的 PATH 设置和 Homebrew shell 初始化能在新窗格中运行。在其他平台上,它保持现有的非登录 shell 行为。用 `"login"` 强制登录 shell 启动,用 `"non_login"` 选择退出。命令窗格、分离式自定义命令按键绑定和显式 argv 启动保持已有的命令执行路径。
+`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` 值仍然优先。
+`new_cwd = "follow"` 保持默认行为，并继承来源窗格或工作区。没有来源工作区时，Herdr 从 `$HOME` 启动。使用 `"home"` 可始终从 `$HOME` 启动，使用 `"current"` 可采用 Herdr 的进程目录，也可以指定 `"~/Projects"` 这样的固定路径。CLI 或 socket API 显式提供的 `--cwd` 值仍然优先。
 
 ## Worktree
 
-设置从侧边栏创建 Git worktree 检出时 Herdr 使用的根目录:
+设置 Herdr 从侧边栏创建 Git worktree 检出时使用的根目录：
 
 ```toml
 [worktrees]
 directory = "~/.herdr/worktrees"
 ```
 
-Herdr 在 `<directory>/<repo>/<branch-slug>` 下创建检出。想要同级目录风格的检出,把它设为 `~/Projects/herdr-worktrees` 这类目录。相对值会在应用配置时解析为绝对路径。
+Herdr 会在 `<directory>/<repo>/<branch-slug>` 下创建检出。若要使用同级目录风格的检出，请将其设置为 `~/Projects/herdr-worktrees` 这样的目录。应用配置时，相对路径会解析为绝对路径。
 
-worktree 操作在 Git 工作区行上可用。`New worktree` 创建一个检出,输入的分支已存在时检出该本地分支,否则创建分支,作为新 Herdr 工作区打开,并归组到来源工作区之下。`Open worktree...` 列出该仓库已有的 Git worktree 检出;选择已打开的检出会聚焦它,选择已关闭的检出会在同一组中打开它。
+Git 工作区行提供 worktree 操作。`New worktree` 会创建检出：如果输入的分支已存在，则检出该本地分支，否则创建该分支；随后将其作为新的 Herdr 工作区打开，并归组到来源工作区下。`Open worktree...` 会列出该仓库现有的 Git worktree 检出；选择已打开的检出会聚焦它，选择尚未打开的检出会在同一组中打开它。
 
-归组的 worktree 仍然像普通 Herdr 工作区一样: 可以聚焦、重命名、关闭,并拥有自己的标签页和窗格。父行是原始工作区。关闭父行会关闭整个 Herdr 组,但不会删除检出文件夹或分支。
+归组的 worktree 仍像普通 Herdr 工作区一样工作：可以聚焦、重命名和关闭，也可以拥有自己的标签页和窗格。父行是原始工作区。关闭父行会关闭整个 Herdr 组，但不会删除检出目录或分支。
 
-删除 worktree 检出是显式操作。在归组的子工作区上使用 `Delete worktree checkout...` 运行 `git worktree remove`。Herdr 先请求 Git 安全删除。如果 Git 因为检出有修改或未跟踪文件而拒绝,Herdr 会在执行强制删除前再次询问。分支不会被删除。
+删除 worktree 检出需要显式操作。在归组的子工作区上使用 `Delete worktree checkout...` 来运行 `git worktree remove`。Herdr 会先请求 Git 安全删除。如果 Git 因检出中存在已修改或未跟踪的文件而拒绝，Herdr 会在强制删除前再次确认。分支不会被删除。
 
 ## 远程连接
 
-远程连接默认用带临时保活兜底的方式管理它的 SSH 桥。
+远程连接默认使用临时保活设置和连接复用兜底来管理 SSH 连接。
 
 ```toml
 [remote]
 manage_ssh_config = true
 ```
 
-启用时,`herdr --remote` 写入一个私有的临时 SSH 配置: 先包含你的 `~/.ssh/config` 和 `/etc/ssh/ssh_config`,再添加兜底的 `ServerAliveInterval` 和 `ServerAliveCountMax` 值。你自己的 SSH 保活设置优先。设置 `manage_ssh_config = false` 用普通 `ssh` 运行桥接,不使用 Herdr 生成的配置。
+启用后，`herdr --remote` 会写入一份私有的临时 SSH 配置：先包含你的 `~/.ssh/config` 和 `/etc/ssh/ssh_config`，再添加兜底的 `ServerAliveInterval` 和 `ServerAliveCountMax` 值。你自己的保活设置优先。Herdr 还会为每次远程连接使用私有的 OpenSSH control socket，以复用首次通过身份验证的连接。设置 `manage_ssh_config = false` 可通过普通 `ssh` 进行远程连接，不使用 Herdr 生成的配置或 control socket。
 
 ## 按键绑定
 
-前缀键的入门介绍和经过验证的免前缀配置,见[键盘](/zh-cn/docs/keyboard/)。
+有关前缀键的引导式介绍和经过验证的免前缀配置，请参阅[键盘](/docs/keyboard/)。
 
-Herdr 有类似 tmux 的前缀模式。默认前缀是 `ctrl+b`。按键绑定字符串是显式的: `prefix+n` 表示先按配置的前缀再按 `n`;`ctrl+alt+n` 是终端模式的直接快捷键。
+Herdr 提供类似 tmux 的前缀模式。默认前缀是 `ctrl+b`。按键绑定字符串是显式的：`prefix+n` 表示先按配置的前缀，再按 `n`；`ctrl+alt+n` 则是终端模式下的直接快捷键。
 
-一个小型的按键绑定覆盖长这样:
+一个简短的按键绑定覆盖如下：
 
 ```toml
 [keys]
@@ -145,73 +128,24 @@ navigate_pane_down = "ctrl+j"
 split_horizontal = "prefix+minus"
 ```
 
-默认键位以前缀为先,避免会从 shell、编辑器、tmux 或终端应用抢输入的直接快捷键。常见默认值包括:
-
-```toml
-[keys]
-detach = "prefix+q"
-workspace_picker = "prefix+w"
-goto = "prefix+g"
-new_workspace = "prefix+shift+n"
-new_worktree = "prefix+shift+g"
-rename_workspace = "prefix+shift+w"
-close_workspace = "prefix+shift+d"
-navigate_workspace_up = "up"
-navigate_workspace_down = "down"
-navigate_pane_left = "h"
-navigate_pane_down = "j"
-navigate_pane_up = "k"
-navigate_pane_right = "l"
-remote_image_paste = "ctrl+v"
-new_tab = "prefix+c"
-previous_tab = "prefix+p"
-next_tab = "prefix+n"
-switch_tab = "prefix+1..9"
-rename_tab = "prefix+shift+t"
-close_tab = "prefix+shift+x"
-copy_mode = "prefix+["
-focus_pane_left = "prefix+h"
-focus_pane_down = "prefix+j"
-focus_pane_up = "prefix+k"
-focus_pane_right = "prefix+l"
-swap_pane_left = "prefix+shift+h"
-swap_pane_down = "prefix+shift+j"
-swap_pane_up = "prefix+shift+k"
-swap_pane_right = "prefix+shift+l"
-cycle_pane_next = "prefix+tab"
-cycle_pane_previous = "prefix+shift+tab"
-last_pane = ""
-split_vertical = "prefix+v"
-split_horizontal = "prefix+minus"
-close_pane = "prefix+x"
-zoom = "prefix+z"
-resize_mode = "prefix+r"
-toggle_sidebar = "prefix+b"
-```
+默认键位以前缀为主，因此 Herdr 不会抢占 shell、编辑器、tmux 或终端应用的输入。在[配置参考](/docs/config-reference/)中搜索 `keys.` 可查看每个动作及其默认绑定。应用内帮助面板可通过 `prefix+?` 打开，其中会显示当前生效的绑定。
 
-可选动作默认未设置。用 `prefix+` 绑定它们获得前缀模式行为,或者在有意想要直接快捷键时用显式的修饰组合键:
+当一个动作需要多个快捷键时，绑定也可以是数组：
 
 ```toml
 [keys]
-previous_workspace = "prefix+shift+left"
-next_workspace = "prefix+shift+right"
-last_pane = "prefix+tab"
-open_worktree = "prefix+shift+o"
-remove_worktree = "prefix+alt+d"
 next_tab = ["prefix+n", "ctrl+alt+]"]
 ```
 
-`last_pane` 跨工作区和标签页切回上一个聚焦的窗格。它默认未设置,因为 tmux 风格的窗格绑定 `prefix+l` 已被用于向右聚焦窗格。
-
-`remote_image_paste` 只在 `herdr --remote` 中生效。它是本地客户端的快捷键,把本地剪贴板图像发送到远程窗格。设为空字符串可禁用这个原始按键快捷键;外层终端发送的 paste-image 信号仍然有效。
+可选动作默认不设置。使用 `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 设置。
+按键字符串支持普通按键、`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 默认值。
+如果你已有旧的自定义按键绑定，并想使用新的默认值，请运行 `herdr config reset-keys`。Herdr 会备份 `config.toml`，移除 `[keys]` 和 `[[keys.command]]`，并在重启或执行 `herdr server reload-config` 后使用内置的 v2 默认值。
 
 ## 索引跳转
 
-索引式按键绑定在普通按键绑定字段中使用 `1..9`:
+索引式按键绑定在普通按键绑定字段中使用 `1..9`：
 
 ```toml
 [keys]
@@ -220,25 +154,48 @@ switch_workspace = "prefix+shift+1..9"
 focus_agent = "prefix+alt+1..9"
 ```
 
-旧式的 `[keys.indexed]` 表出于兼容仍会被解析,但新配置应优先使用显式的动作字段。
+旧版 `[keys.indexed]` 表仍会出于兼容性而解析，但新配置应优先使用显式的动作字段。
 
 ## 自定义命令按键绑定
 
-自定义命令使用同样的按键绑定语法。
+自定义命令使用相同的按键绑定语法。
 
 ```toml
 [[keys.command]]
 key = "prefix+alt+g"
-type = "pane"
+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%"
 ```
 
-`type = "pane"` 打开一个临时窗格,并在命令退出时关闭它。
+在 Windows 上,请改用 `command = "powershell.exe -NoLogo"` 之类的 shell 命令。
+退出 shell 即可关闭弹窗并恢复平铺终端视图。
+
+`type = "pane"` 会打开一个临时窗格，并在命令退出时关闭它。
 
-`type = "shell"` 在后台分离运行。
+`type = "shell"` 会在后台分离运行。
 
-`type = "plugin_action"` 调用已安装插件的动作 id。动作 id 不全局唯一时使用限定 id:
+`type = "plugin_action"` 会调用已安装插件的动作 id。当动作 id 并非全局唯一时，请使用限定 id：
 
 ```toml
 [[keys.command]]
@@ -248,26 +205,24 @@ command = "example.layout.apply"
 description = "apply layout"
 ```
 
-可以提供可选的 `description`。指定后,它会显示在按键帮助面板 (`prefix+?` 打开) 中,替代默认的 `'custom command'` 标签。
+可以提供可选的 `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 命令会从该目录运行。
 
-自定义命令在可用时会收到 `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`。
 
-`catppuccin`、`catppuccin-latte`、`terminal`、`tokyo-night`、`tokyo-night-day`、`dracula`、`nord`、`gruvbox`、`gruvbox-light`、`one-dark`、`one-light`、`solarized`、`solarized-light`、`kanagawa`、`kanagawa-lotus`、`rose-pine`、`rose-pine-dawn`、`vesper`。
-
-想让 Herdr 的 UI 颜色跟随宿主终端的 ANSI 调色板时用 `terminal`。
-
-要让 Herdr 在宿主终端报告明暗外观变化时自动切换自己的 UI 主题,启用主题自动切换:
+要让 Herdr 在宿主终端报告明暗外观变化时自动切换自身的 UI 主题，请启用主题自动切换：
 
 ```toml
 [theme]
@@ -277,9 +232,9 @@ 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`。
+`auto_switch` 默认为 `false`，因此现有主题配置会保持手动行为。如果省略 `light_name` 或 `dark_name`，且配置的 `name` 存在对应的内置姊妹主题，Herdr 会使用该主题，例如 `tokyo-night`/`tokyo-night-day` 或 `gruvbox`/`gruvbox-light`。在设置中手动选择主题会禁用 `auto_switch`。
 
-你可以覆盖单个颜色:
+你可以覆盖单个颜色：
 
 ```toml
 [theme.custom]
@@ -291,98 +246,116 @@ red = "#f38ba8"
 yellow = "#f9e2af"
 ```
 
-颜色值接受十六进制、命名颜色、`rgb(r,g,b)`,或 `reset`、`default`、`none`、`transparent` 这类重置别名。
+颜色值支持十六进制、命名颜色、`rgb(r,g,b)`，以及 `reset`、`default`、`none`、`transparent` 等重置别名。
 
 ## UI 与侧边栏
 
-侧边栏是 Herdr 的主仪表盘。它显示工作区、标签页、窗格和智能体状态。
-
-常用选项:
-
-```toml
-[ui]
-sidebar_width = 32
-sidebar_min_width = 18
-sidebar_max_width = 36
-mobile_width_threshold = 64
-mouse_capture = true
-right_click_passthrough_modifier = ""
-redraw_on_focus_gained = true
-mouse_scroll_lines = 3
-confirm_close = true
-prompt_new_tab_name = true
-pane_borders = true
-pane_gaps = true
-show_agent_labels_on_pane_borders = false
-agent_panel_sort = "spaces"
-accent = "cyan"
-```
-
-`sidebar_min_width` 和 `sidebar_max_width` 以列数控制展开侧边栏的调整范围。默认是 18 和 36。
+侧边栏是 Herdr 的主仪表盘。在[配置参考](/docs/config-reference/)中搜索 `ui.`，可查看尺寸、折叠模式、Agent 面板排序、鼠标行为、窗格边框和其他显示设置。
 
-`mobile_width_threshold` 控制 Herdr 使用移动端单列布局的终端宽度阈值。默认 64 列;折叠屏、平板或宽屏手机终端可以调大。
+### 侧边栏行布局
 
-智能体面板显示所有空间中的所有智能体。`agent_panel_sort` 可以是 `spaces` 或 `priority`;`workspaces` 作为 `spaces` 的别名被接受。默认是 `spaces`,让智能体按空间顺序分组。`priority` 按关注优先级排序: blocked、done、working、idle,然后是 unknown。同一状态内,最近改变状态的智能体排在前面。
+展开的桌面侧边栏会将 `rows` 中的每个内层数组渲染为一行。以下是完整的默认布局：
 
-`confirm_close` 控制关闭工作区时是否需要确认。`prompt_new_tab_name` 控制新标签页是否先询问名称。
+```toml
+[ui.sidebar.agents]
+row_gap = 0
+rows = [
+  ["state_icon", "workspace", "tab"],
+  ["agent"],
+]
 
-如果想让终端处理普通点击,比如 command+点击 URL,设置 `mouse_capture = false`。鼠标捕获启用时,如果终端把带修饰键的点击传给 Herdr,Ctrl+点击可以打开窗格链接。macOS 也是如此;Herdr 捕获鼠标输入期间,Cmd+点击不会与普通点击区分上报。终端原生的绕过路径: Linux 上用 Shift+Ctrl+点击,macOS 上用 Shift+Cmd+点击。
+[ui.sidebar.spaces]
+row_gap = 0
+rows = [
+  ["state_icon", "workspace"],
+  ["branch", "git_status"],
+]
+```
 
-如果想让 Ctrl+右键点击、按住和拖动手势到达启用鼠标上报的窗格应用,而不是打开 Herdr 的窗格菜单,设置 `right_click_passthrough_modifier = "ctrl"`。默认为空,即禁用这种透传。支持的修饰键有 `ctrl`、`alt`、`cmd`、`super`、`meta` 和 `hyper`;`shift` 被拒绝,因为许多终端把 Shift+鼠标保留给它们自己的鼠标绕过。
+Agent 行支持以下内置 token：
 
-设置 `redraw_on_focus_gained = false` 可以避免切回 Herdr 时可见的全屏刷新。默认为 `true`,因为完整重绘能从罕见的过期或脏的宿主终端画面中恢复。
+- `state_icon` — 智能体语义状态的彩色图标。
+- `state_text` — `idle`、`working`、`blocked`、`done` 或 `unknown`；如果报告中包含显示标签，也会一并显示。
+- `workspace` — 工作区名称。
+- `tab` — 标签页名称（如有）。
+- `pane` — 窗格名称（如有）。
+- `agent` — 检测到或报告的智能体显示名称。
+- `terminal_title` — 经过安全规范化的最新 OSC 0/2 终端标题。
+- `terminal_title_stripped` — 从终端标题开头移除一个可识别的活动或旋转指示符字形及其后空白后的结果。
+- `$name` — 名为 `name` 的自定义窗格元数据。
 
-设置 `mouse_scroll_lines` 改变鼠标滚轮每格滚动的窗格回滚行数。默认是 3。请求鼠标上报的窗格应用仍然直接接收滚轮事件。备用屏幕应用没有可滚动的回滚内容;参见[回滚缓冲区](#回滚缓冲区)。
+Space 行支持以下内置 token：
 
-设置 `pane_borders = false` 移除分割窗格边框。设置 `pane_gaps = false` 让分割窗格共用紧凑的分隔线。禁用边框时,窗格间距是窗格之间一个空白终端单元格。终端单元格通常高大于宽,所以上下窗格之间一行的间距可能看起来比左右窗格之间一列的间距更大。
+- `state_icon` — Space 汇总后智能体状态的彩色图标。
+- `state_text` — Space 汇总后智能体状态的文本。
+- `workspace` — 工作区名称。
+- `branch` — Git 分支（如有）。
+- `git_status` — 非零时显示 Git ahead 和 behind 数量。
+- `$name` — 名为 `name` 的自定义工作区元数据。
 
-如果想在没有手动窗格标签时,把检测到的智能体标签显示在分割窗格边框上,设置 `show_agent_labels_on_pane_borders = true`。
+token 会按配置顺序渲染。Herdr 通常使用 ` · ` 分隔相邻值，并在 `state_icon` 后使用一个空格。缺失值及其分隔符会消失；当一行中的所有 token 都没有值时，该行会消失。每个布局最多可包含 16 行，每行最多可包含 16 个 token。
 
-## 通知
+`row_gap` 分别控制 Agent 和 Space 面板中条目之间的空白终端行数。默认值为 `0`，会紧密排列条目；设为 `1` 可恢复之前的间距。它不会在 `rows` 声明的内容行之间添加间距。连续缩进的 worktree 子项仍会作为一个 Space 组紧密排列。
 
-Herdr 可以在智能体完成或需要输入时显示弹出通知。
+在 `rows_by_agent` 下为已知智能体覆盖完整的 Agent 布局：
 
 ```toml
-[ui.toast]
-delivery = "off"
-delay_seconds = 1
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "agent", "state_text"],
+  ["workspace", "tab"],
+]
 
-[ui.toast.herdr]
-position = "bottom-right"
-
-[ui.toast.clipboard]
-enabled = true
-position = "bottom-center"
+[ui.sidebar.agents.rows_by_agent]
+claude = [
+  ["state_icon", "agent", "state_text"],
+  ["terminal_title_stripped"],
+  ["workspace", "tab"],
+]
 ```
 
-`delivery = "off"` 禁用弹出通知。这是默认值。
-
-`delivery = "herdr"` 在 Herdr UI 内显示 toast。点击 toast,或绑定 `keys.open_notification_target`,可以聚焦目标工作区、标签页和窗格。`ui.toast.herdr.position` 可设为 `top-left`、`top-right`、`bottom-left` 或 `bottom-right`;桌面位置相对于完整的 Herdr 画面。
+覆盖项会替换 `rows`，而不是扩展它。覆盖项的键是区分大小写的规范智能体 ID，例如 `claude`、`codex` 和 `pi`。不接受 `claude-code` 等检测别名。没有覆盖项的智能体（包括自定义报告的智能体）会使用 `rows`。
 
-`delivery = "terminal"` 请求外层终端显示桌面通知。Herdr 为 Ghostty、iTerm2、Kitty 和 WezTerm 发送终端通知转义序列。在 SSH 上很有用,因为通知归本地终端所有。
+自定义 `$name` token 是动态值，而不是字面文本。先将 token 添加到布局，再通过脚本或插件报告其值：
 
-`delivery = "system"` 直接请求本地操作系统。在 macOS 上,Herdr 优先使用 `terminal-notifier`,不可用时回退到 `/usr/bin/osascript`。`terminal-notifier` 可以在你点击通知时激活承载的终端。在 Linux 上,Herdr 使用 `notify-send`,并要求 `DISPLAY` 或 `WAYLAND_DISPLAY`。
+```toml
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "agent", "$model"],
+  ["$summary"],
+  ["workspace", "tab"],
+]
+```
 
-弹出通知用于后台提醒。Herdr 对活动标签页抑制弹出。
+```bash
+herdr pane report-metadata <pane_id> \
+  --source my-agent-hook \
+  --token model=opus \
+  --token summary="reviewing authentication"
+```
 
-`delay_seconds` 在发送完成或需要输入的智能体通知前等待。只有在延迟结束时窗格仍处于相同状态,Herdr 才会通知。设为 `0` 立即通知。有效值为 `0` 到 `3600`。
+自定义 Space token 可用同样的方式通过 `herdr workspace report-metadata` 报告。未报告的自定义 token 会直接消失。元数据报告方只提供值，不能选择行或样式。有关清除、顺序和过期值的信息，请参阅 [CLI 参考：报告元数据](/docs/cli-reference/#panes)。
 
-剪贴板反馈单独配置,因为它确认的是前台复制操作,并且从不通过 terminal 或 system 投递。设置 `ui.toast.clipboard.enabled = false` 隐藏“已复制到剪贴板”弹窗。剪贴板位置有 `top-left`、`top-center`、`top-right`、`bottom-left`、`bottom-center` 和 `bottom-right`。
+侧边栏行设置仅影响展开的桌面侧边栏。折叠视图和移动视图仍使用紧凑布局。
 
-## 声音
+## 通知
 
-声音通知默认启用,由本地 Herdr 客户端播放。
+当后台智能体完成任务或需要输入时，Herdr 可以通知你：
 
 ```toml
-[ui.sound]
-enabled = true
+[ui.toast]
+delivery = "herdr"
+delay_seconds = 1
+
+[ui.toast.herdr]
+position = "bottom-right"
 ```
 
-Herdr 在智能体完成时播放完成音,在智能体需要输入时播放提醒音。在共享机器或远程服务器上,除非明确想要声音,否则设置 `enabled = false`。
+选择 `herdr` 可使用应用内 toast，选择 `terminal` 可使用适合 SSH 场景的外层终端通知，选择 `system` 可使用本地操作系统通知服务，选择 `off` 可禁用弹出通知。Herdr 会抑制活动标签页的弹出通知。在[配置参考](/docs/config-reference/)中搜索 `ui.toast`，可查看位置、延迟行为和剪贴板反馈设置。
 
-在 macOS 上,Herdr 使用 `afplay`。在 Linux 上,Herdr 按顺序尝试支持 mp3 的播放器: `paplay`、`pw-play`、`ffplay`、`mpg123`,然后是 `mpv`。没有可用播放器时,声音播放被跳过,Herdr 记录一条警告。
+## 声音
 
-自定义声音必须是 mp3 文件。相对路径从配置文件所在目录解析。
+声音通知通过本地 Herdr 客户端播放。自定义声音必须是 mp3 文件；相对路径从配置文件所在目录解析。
 
 ```toml
 [ui.sound]
@@ -391,9 +364,9 @@ done_path = "sounds/done.mp3"
 request_path = "sounds/request.mp3"
 ```
 
-`path` 为所有声音通知设置一个声音。`done_path` 和 `request_path` 只覆盖完成音和需要输入音。
+`path` 为所有声音通知设置同一种声音。`done_path` 和 `request_path` 只覆盖完成和需要输入时的声音。
 
-按智能体的声音覆盖接受 `default`、`on` 或 `off`。用检测到的智能体标签做键,比如 `claude`、`codex`、`devin` 或 `droid`。Droid 默认静音。
+按智能体覆盖声音设置时，可使用 `default`、`on` 或 `off`。键应使用检测到的智能体标签，例如 `claude`、`codex`、`devin` 或 `droid`。Droid 默认静音。
 
 ```toml
 [ui.sound.agents]
@@ -401,110 +374,54 @@ droid = "off"
 claude = "on"
 ```
 
-## 回滚缓冲区
-
-设置新建窗格的回滚缓冲区大小:
-
-```toml
-[advanced]
-scrollback_limit_bytes = 10485760
-```
-
-现有窗格在重建之前保持当前缓冲区。
-
-只有应用写入主屏幕时,窗格才显示滚动条。切换到备用屏幕的全屏应用 (vim、htop、设置了 `CLAUDE_CODE_NO_FLICKER=1` 的 Claude Code) 不产生回滚内容,因此不出现滚动条,滚轮事件转而路由给应用。请用应用自己的按键或 UI 滚动。
-
-## 窗格屏幕历史
-
-默认情况下,完整的会话重启会恢复工作区、标签页、窗格、cwd、布局和焦点,但不保存窗格内容。
-
-窗格屏幕历史默认关闭。窗格输出可能包含密钥、令牌、提示词和命令输出,所以只在你确实想让 Herdr 跨完整服务器重启保存最近窗格内容时才开启:
-
-```toml
-[experimental]
-pane_history = true
-```
-
-也可以在 Settings > Experiments > pane screen history 中切换。
-
-开启后,Herdr 把保存的窗格历史存放在 `session.json` 旁边的 `session-history.json` 中。
-
-窗格屏幕历史与实时持久化、快照恢复、智能体原生会话恢复和实时交接的区别,见[会话状态与恢复](/zh-cn/docs/session-state/)。
-
-## 嵌套启动
-
-Herdr 通常会阻止你在 Herdr 内启动 Herdr。
-
-```toml
-[experimental]
-allow_nested = false
-```
+## 高级配置
 
-仅在测试时启用嵌套启动。
+在[配置参考](/docs/config-reference/)中搜索回滚缓冲区限制、嵌套启动以及其他高级或实验性设置。启用窗格屏幕历史前，请参阅[会话状态与恢复](/docs/session-state/)；该指南说明了保存窗格内容带来的安全取舍。
 
 ## Kitty graphics
 
-Kitty graphics 支持是实验性的。
+面向已连接本地客户端的 Kitty graphics 渲染是一项实验性功能，默认禁用：
 
 ```toml
 [experimental]
-kitty_graphics = false
+kitty_graphics = true
 ```
 
-除非你在测试终端图像行为,否则保持关闭。
+仅在测试终端图像行为时启用。
 
 ## 智能体会话恢复
 
-Herdr 可以在服务器重启后,让受支持的智能体窗格在其原生对话会话中重新启动。
+默认情况下，Herdr 会在服务器重启后恢复受支持的智能体对话：
 
 ```toml
 [session]
 resume_agents_on_restore = true
 ```
 
-这默认开启。Herdr 只恢复通过官方 Herdr 集成上报了原生会话引用的窗格。受支持的恢复目标是 Claude Code、Codex、Cursor Agent CLI、GitHub Copilot CLI、Droid、Kimi Code CLI、Qoder CLI、Pi、Hermes Agent、OpenCode、Kilo Code CLI 和 MastraCode。不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。
-
-会话引用存储在本地 Herdr 会话快照中。它们不会出现在普通的窗格、智能体、状态或事件输出中。
-
-智能体原生会话恢复与窗格屏幕历史和实时交接的区别,见[会话状态与恢复](/zh-cn/docs/session-state/)。
+只有通过官方集成获得有效原生会话引用的窗格才能恢复；其他窗格会作为普通 shell 恢复。有关受支持的智能体和持久化行为，请参阅[会话状态与恢复](/docs/session-state/)。
 
 ## IME 光标跟踪
 
-当聚焦窗格隐藏光标并自己绘制光标时 — 这在 Claude Code、pi、codex、Devin 这类 AI 智能体 TUI 中很常见 — macOS 原生输入法会停止跟踪候选窗口位置,因为外层终端不再报告光标。
-
-设置 `reveal_hidden_cursor_for_cjk_ime = true`,无视窗格的 `?25l` 请求,把聚焦窗格的光标锚点暴露给外层终端:
+在 macOS 上，隐藏硬件光标的 AI 智能体 TUI 可能导致原生输入法候选窗口无法跟随聚焦窗格。使用以下设置可为这些窗格显示光标锚点：
 
 ```toml
 [experimental]
-reveal_hidden_cursor_for_cjk_ime = false
-cjk_ime_agents = []
-cjk_ime_cursor_shape = "steady_block"
+reveal_hidden_cursor_for_cjk_ime = true
+cjk_ime_agents = ["claude", "pi", "codex"]
 ```
 
-启用后,光标保持在聚焦窗格上报的位置可见。如果窗格没有上报光标位置,锚点回退到窗格左上角,保证始终有稳定的输入法提示位置。
-
-`cjk_ime_agents` 是可选的允许列表。为空时,该显示适用于任何聚焦窗格。非空时,只在聚焦窗格检测到的智能体匹配列表中某个名称时才生效 — 适合只对自绘光标的 AI 智能体 TUI 启用,而不影响普通 shell。接受的名称: `pi`、`claude`、`codex`、`gemini`、`cursor`、`devin`、`agy`、`cline`、`opencode`、`copilot`、`kimi`、`kiro`、`droid`、`amp`、`grok`、`hermes`、`kilo`、`qodercli` 和 `qoder`。未知名称被忽略;如果列表中没有有效名称,该显示不生效。
+限制 `cjk_ime_agents` 可以避免在无关应用中额外显示硬件光标。在[配置参考](/docs/config-reference/)中搜索这些键，可查看接受的智能体名称和光标形状。
 
-`cjk_ime_cursor_shape` 控制为输入法锚点渲染的 DECSCUSR 形状。接受的值: `block`、`steady_block` (默认)、`underline`、`steady_underline`、`bar`、`steady_bar`。
+## 前缀输入源切换
 
-通过已有的 `[experimental]` 块热重载。
-
-启用的代价: 对隐藏光标但不绘制替代光标的应用 (vim 普通模式等),外层终端会多显示一个硬件光标。配合 `cjk_ime_agents` 把它限定到特定 TUI。
-
-## 前缀输入法切换
-
-在 macOS 上,当非 ASCII 输入法处于活动状态时,前缀模式命令可能很难使用,因为前缀命令仍会经过宿主输入法解释。
-
-设置 `switch_ascii_input_source_in_prefix = true`,在前缀模式激活期间把宿主输入法切换到系统的 ASCII 输入法:
+在 macOS 上，当前缀命令和由前缀启动的模式处于活动状态时，Herdr 可以临时切换到系统中支持 ASCII 的输入源：
 
 ```toml
 [experimental]
-switch_ascii_input_source_in_prefix = false
+switch_ascii_input_source_in_prefix = true
 ```
 
-启用后,Herdr 只在进入前缀模式后切换输入法,并在退出前缀模式时恢复之前的输入法。该设置仅限 macOS,在其他平台或系统输入法切换失败时不做任何事。
-
-也可以在 Settings > Experiments > switch to ascii input source in prefix (macOS) 中切换。
+返回终端输入或进入文本字段时，Herdr 会恢复之前的输入源。此设置在其他平台上无效。
 
 ## 环境变量
 
@@ -512,15 +429,15 @@ switch_ascii_input_source_in_prefix = false
 | --- | --- |
 | `HERDR_CONFIG_PATH` | 覆盖配置文件路径。 |
 | `HERDR_SESSION` | 为 CLI 命令选择命名会话。 |
-| `HERDR_SOCKET_PATH` | 底层 socket 路径覆盖。 |
-| `HERDR_LOG` | 设置日志过滤,例如 `HERDR_LOG=herdr=debug`。 |
+| `HERDR_SOCKET_PATH` | 覆盖底层 socket 路径。 |
+| `HERDR_LOG` | 设置日志过滤，例如 `HERDR_LOG=herdr=debug`。 |
 | `HERDR_DISABLE_SOUND` | 即使 `[ui.sound] enabled = true` 也禁用声音播放。 |
 
 ## 日志
 
-诊断启动警告、集成状态或 socket API 行为时,日志很有用。
+日志有助于诊断启动警告、集成状态或 socket API 行为。
 
-常见日志文件:
+常见日志文件：
 
 ```text
 ~/.config/herdr/herdr.log
@@ -528,4 +445,4 @@ switch_ascii_input_source_in_prefix = false
 ~/.config/herdr/herdr-server.log
 ```
 
-日志自动轮转。报告问题时请附上当前日志和已轮转的同级文件。
+日志会自动轮转。报告问题时，请附上当前日志和轮转后的同级日志文件。