---
url: /wave-agent/specs/commands/hooks-command.md
description: '`/hooks` 浏览用户/项目/插件三级作用域的已配置钩子与各 HookEvent 事件摘要，CLI 只读覆盖层与 IDE 设置页钩子选项卡'
---

# 功能规格说明：/hooks 斜杠命令

**创建日期**：2026-09-02

> 对齐 Claude Code 的 `/hooks` 命令（`local-jsx`、`immediate`，打开只读的 HooksConfigMenu 浏览已配置钩子，编辑引导用户改 settings.json 或让 Claude 配置）。覆盖 CLI 与图形界面三端（VS Code 扩展 / JetBrains 插件 / 桌面端）两种入口：CLI 为终端管理器覆盖层（只读浏览），图形界面三端打开设置页并选中「钩子」选项卡（`/hooks` → 钩子，复用 `/skills` → 技能、`/agents` → 子代理的现有模式）。事件摘要元数据（每个 HookEvent 一句说明）对齐 CC 的 `HookEventMetadata.summary`，CLI 详情页与 webview 钩子页共用。

## 用户场景与测试 *（必填）*

### 用户故事：浏览已配置钩子（优先级：P1）

作为 CLI 用户，我希望通过 `/hooks` 命令查看当前环境已配置的所有钩子，按来源（用户级 / 项目级 / 插件）分组浏览事件、匹配器与命令，以便了解哪些钩子在生效、来自哪里，而无需打开 settings.json 手动查找。

**为什么是这个优先级**：钩子默认在后台触发，用户缺乏可见性；浏览是钩子管理的基础（对齐 Claude Code 的 `/hooks` 命令——只读浏览，新增/修改引导用户编辑 settings.json 或直接让 AI 配置，菜单内不做编辑）。

**独立测试**：可以通过在聊天中输入 `/hooks` 并验证覆盖层显示按来源分组的钩子列表、可进入详情查看完整配置、可导航并关闭来完整测试。

**验收场景**：

1. **假设** 环境中存在至少一个已配置钩子，**当** 用户在聊天中输入 `/hooks`，**则** 显示钩子管理覆盖层，按来源分组列出所有已配置钩子（用户级 / 项目级 / 插件）
2. **假设** 钩子管理覆盖层已打开，**当** 用户按 `↑`/`↓` 键，**则** 选中高亮在钩子条目间移动（分组标题不可选中）
3. **假设** 钩子管理覆盖层已打开，**当** 用户按 `Esc` 键，**则** 覆盖层关闭，对话界面恢复且不产生任何消息
4. **假设** 环境中没有任何已配置钩子，**当** 用户执行 `/hooks`，**则** 显示空状态提示及钩子配置位置指引（如 `~/.wave/settings.json` 的 `hooks` 字段或让 AI 配置）

***

### 用户故事：查看钩子详情（优先级：P2）

作为 CLI 用户，我希望选中一个钩子后查看其完整配置（事件、事件说明、匹配器、全部命令、超时、异步），以便判断该钩子是否符合预期以及是否需要调整。

**为什么是这个优先级**：列表条目只展示摘要（事件:匹配器 + 首条命令），完整配置与事件说明帮助用户核对细节；事件说明对齐 CC 的 `HookEventMetadata.summary`（2026-09-02 用户拍板：事件摘要纳入本次实现）。

**独立测试**：可以通过在列表中选择钩子并按 `Enter` 验证详情视图渲染完整配置与事件说明来测试。

**验收场景**：

1. **假设** 钩子管理覆盖层已打开且某钩子被选中，**当** 用户按 `Enter`，**则** 进入该钩子的详情视图，显示事件、事件说明（一句摘要）、匹配器（无匹配器时省略）、所有配置命令、超时、异步标记
2. **假设** 详情视图已打开，**当** 用户按 `Esc` 或 `Enter`，**则** 返回列表视图
3. **假设** 详情视图已打开，**当** 用户按 `Esc` 两次（列表态再按一次），**则** 覆盖层关闭

***

### 用户故事：图形界面三端打开设置页钩子选项卡（优先级：P1）

作为 图形界面三端（VS Code 扩展 / JetBrains 插件 / 桌面端）用户，我希望通过 `/hooks` 斜杠命令直接唤起设置页面并选中「钩子」选项卡，以查看、新建、编辑与删除当前会话可见的钩子（按来源 Tab 展示），以便在不切换到 CLI 的情况下管理钩子。

**为什么是这个优先级**：CLI 有 `/hooks`；图形界面三端的用户需要对等入口。设置页（批次 2）已提供「钩子」导航项（`SettingsHooksView`，支持按来源 Tab 展示与新建/编辑/删除，见 hooks.md），`/hooks` 复用设置页入口避免维护独立的钩子对话框（2026-08-29 用户拍板：钩子弹窗内容迁移到设置页选项卡，与 `/skills` → 技能、`/agents` → 子代理一致）。

**独立测试**：在图形界面三端中输入 `/hooks`，验证打开设置页并选中「钩子」选项卡，按来源 Tab 列出钩子；执行新增/编辑/删除操作；点击「返回」关闭设置页回到会话。

**验收场景**：

1. **假设** 用户处于图形界面三端（VS Code 扩展 / JetBrains 插件 / 桌面端），**当** 用户输入 `/hooks` 并发送，**则** 打开设置页并选中「钩子」选项卡（桌面端打开全页设置，IDE 打开编辑器区域设置标签页），不再弹出独立对话框
2. **假设** 设置页「钩子」选项卡已打开，**则** 顶部展示「用户级钩子 / 项目级钩子 / 插件钩子」三个来源 Tab，默认选中用户级，每项展示钩子名（`Event:Matcher`）、事件说明（一句摘要，对齐 CC `HookEventMetadata.summary`）、命令
3. **假设** 用户位于「用户级钩子」或「项目级钩子」Tab，**当** 用户点击「新增钩子」，**则** 关闭设置页回到会话视图，AI 对话框打开并预填新建钩子提示词（行为沿用 hooks.md「新建钩子」故事）
4. **假设** 用户点击某钩子的「编辑」或「删除」，**则** 行为沿用 hooks.md「编辑钩子」「删除钩子」故事（编辑预填提示词并打开 settings.json，删除二次确认后直接删配置）
5. **假设** 设置页已打开，**当** 用户点击「返回」或切换其他选项卡，**则** 回到会话视图或切换到对应选项卡，设置页不产生任何消息

***

### 边界情况

* **无钩子**：环境中没有任何钩子时，CLI 覆盖层显示空状态与配置指引（`~/.wave/settings.json` 的 `hooks` 字段），而不是空白面板；GUI 设置页钩子选项卡显示空状态提示
* **同名钩子存在于多个来源**：各来源分组独立展示，不合并也不覆盖（用户级与项目级同名钩子均生效，项目级优先级更高由执行层保证）
* **钩子名展示**：有 matcher 的钩子展示为 `Event:Matcher`（如 `PreToolUse:Write`），无 matcher 的仅展示事件名（如 `Stop`）
* **命令过长**：列表展示命令摘要（截断），详情视图完整显示
* **大列表滚动**：钩子数量超过可视区域时，列表可滚动且选中项保持在可视区域内
* **覆盖层打开期间钩子配置变更**：CLI 覆盖层为打开瞬间的快照，不实时刷新，下次打开反映最新配置；GUI 设置页以 host 下发的 `hooksResponse` 为准
* **GUI 中 host 拉取钩子配置失败**：设置页钩子选项卡展示空态或错误提示，不阻塞输入、不影响会话（host 返回空对象）
* **事件摘要未知**：SDK 未覆盖的钩子事件（如插件自定义事件）在 CLI 详情与 webview 列表回退显示事件名本身，不展示摘要