docs: finalize next release documentation

1 files changed, 23 insertions, 2 deletions

diff --git a/website/src/content/docs/zh-cn/plugins.mdx b/website/src/content/docs/zh-cn/plugins.mdx
index 8d3ba6fc..a22e56b8 100644
--- a/website/src/content/docs/zh-cn/plugins.mdx
+++ b/website/src/content/docs/zh-cn/plugins.mdx
@@ -235,11 +235,32 @@ shell 插件可以从各个环境变量读取常用 id,或解析上下文 JSON �
 
 清单中窗格的 `placement` 默认为 `overlay`,它在活动窗格上方打开一个
 临时的缩放覆盖层,关闭时恢复之前的焦点和缩放。`plugin.pane.open` 请求
-可以用 `overlay`、`split`、`tab` 或 `zoomed` 覆盖清单的 placement。
+可以用 `overlay`、`popup`、`split`、`tab` 或 `zoomed` 覆盖清单的 placement。
 
-插件窗格打开后就是普通的 Herdr 窗格。插件可以通过 socket 或 CLI 调用
+`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`。