docs: finalize release docs and refresh agent skill

1 files changed, 76 insertions, 6 deletions

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
 ```
 
 智能体等待观察的是语义状态,不是任意命令的完成。