---
url: /wave-agent/desktop.md
---

# CodeWave IDE 桌面端

## 1. 快速开始

### 1.1 安装 CodeWave IDE 桌面端

登录企业运营平台，「产品下载」页面下载对应操作系统的安装包（macOS / Windows）。

![产品下载](/guide/product-download.webp)
*产品下载页面*

### 1.2 打开项目

#### 1）导入本地文件夹

选择本地，选择工作目录 --> 点击"浏览"，打开本地文件夹；从本地选择一个文件夹并打开。

* 最近打开列表最多保留 10 个目录，按最近使用排序；hover 条目可点 × 移除
* 会话开始后如需换目录，点击侧边栏「新对话」或直接在会话树中切换
* 从选择器选定任意目录（最近打开列表项、「浏览…」选定的本地目录，或远程目录浏览面板确认的远端目录）**一律开始一个全新会话**，不会复用该目录下已存在的会话；要回到某条已有会话，请走侧边栏会话树

![工作目录选择](/screenshots/desktop-workdir-dropdown.webp)

#### 2）连接SSH远程主机

点击"添加主机"，输入主机地址，接受 `ssh user@hostname -p port` 形式的连接串，连接成功后点击"浏览"，选择文件夹。

整个 CLI 子进程经 `ssh <host> -- wave --stdio` 在远端执行，agent 的读写、搜索、bash、git 等全部工具天然作用在远端文件系统，体验与 VS Code Remote-SSH 一致。

![主机选择器](/screenshots/desktop-ssh-host-selector.webp)

![添加主机](/screenshots/desktop-ssh-add-host.webp)

![远程目录浏览](/screenshots/desktop-remote-dir-browser.webp)

连接远端主机后，右侧面板同样作用在远端机器上：终端面板跑的是远端 shell 的 PTY，差异面板读的是远端工作区的 git 状态，都不需要先把代码同步到本地。

![远端终端面板](/screenshots/desktop-ssh-remote-terminal.webp)

![远端差异面板](/screenshots/desktop-ssh-remote-diff.webp)

#### 3）接入本机 WSL 发行版（仅 Windows）

本机装有 WSL 2 发行版时，主机下拉里会多出一个「WSL 发行版」分组（在「本地」之后、「SSH 主机」之前），选中其一即把会话开在该发行版内：工作目录从发行版文件系统里选（形如 `/home/me/repo`），终端、差异、文件面板与 bash / git 等工具全部作用在发行版内，体验与本地会话一致——不必为了在自己的 Linux 环境里干活先配一套 sshd。

发行版内**不需要预装 Node.js**：CLI 与匹配发行版平台的 Node 运行时都由 Windows 侧下载后经 `wsl.exe` 推入，发行版不出网也能开会话。WSL 1 发行版以禁用状态列出并标注「WSL 1：不支持」；发行版的安装、启动与关闭由你在系统内自行完成，应用只负责接入。

与 SSH 远端的两点差异：会话随应用退出而结束（不像 SSH 远端有 daemon 托管、关掉应用仍在跑）；消息或终端里的 `http://localhost:<port>` 链接借助 WSL 2 的 localhost 转发直接在预览面板打开，不做端口转发。

#### 4）工作目录为git仓库

当你选择的工作目录是 git 仓库、且处于新会话状态（消息列表为空）时，工作目录选择器旁会显示分支选择器与「worktree」勾选项，让你在基于所选分支创建的临时 worktree 中开会话，并行试验而不污染主工作区。

![worktree 控件](/screenshots/desktop-worktree-controls.webp)

![worktree 分支选择](/screenshots/desktop-worktree-branches.webp)

### 1.3 智能输入

#### 1）图片/文件输入

* 点击"+"图标，选择上传文件，可以选择图片/文件上传。
* 可通过 Ctrl/Cmd+V 在对话输入框内粘贴剪贴板中的图片。
* 点击粘贴进来的图片标签，可直接预览图片（用 `@` 选中的图片文件是普通文件引用，点不开）。

![添加菜单](/screenshots/desktop-plus-menu.webp)

#### 2）指令输入

通过输入 `/`，用户可以快速调用预设的指令，如 `/explain`、`/fix` 等提高操作效率。

![指令菜单](/screenshots/desktop-slash-commands.webp)

#### 3）@提及

通过输入 `@`，用户可以轻松地将项目中的文件添加到对话上下文中。标签会内联显示在输入框和消息中。

![@提及标签](/screenshots/desktop-inline-mentions.webp)

#### 4）快捷终端命令

用户可以通过在输入框中以 `!` 开头直接执行终端命令。这允许用户在不离开聊天界面的情况下快速执行系统操作、运行脚本或检查环境。

* **快速触发**：只需在命令前加上 `!` 即可触发，如 `!ls -la`。
* **输出**：命令结束后完整输出一次性显示在专用的 Bang 块中，风格与 AI 触发的终端工具保持一致。
* **状态反馈**：通过图标直观展示命令的运行状态（运行中、退出代码等）。
* **可中止性**：对于长时间运行的命令，用户可以点击"停止"按钮随时中止执行。

![快捷终端命令](/screenshots/desktop-bang-command.webp)

#### 5）旁路提问

`/btw <question>` 向 AI 快速提问，AI 不会调用任何工具，仅基于已有上下文直接回答。适合快速确认思路或获取解释，不产生工具调用开销，也不会进入聊天历史。

* **旁路面板**：发送 `/btw` 后，问题与答案显示在输入框上方的独立面板中，不插入消息列表，聊天上下文不受干扰。
* **Markdown 渲染**：答案支持 Markdown 格式（代码块、列表、加粗等），面板内可滚动查看长内容。
* **随时关闭**：按 Esc 或点击面板右上角关闭按钮即可收起面板；关闭后迟到的回答会被丢弃。
* **错误提示**：接口异常时面板内显示 `(API error: ...)` 提示。

![旁路提问面板](/screenshots/desktop-btw-panel.webp)

### 1.4 面板介绍

对话级侧面板与聊天区并排展示，通过顶栏「面板」菜单多选开关（可同时开启多个），各分屏的面板开关状态与内容相互独立。快捷键：预览 `⇧⌘P`（Windows `Ctrl+Shift+P`）、差异 `⇧⌘D`（`Ctrl+Shift+D`）、终端 `` ⌃` ``（`` Ctrl+` ``）；计划与文件面板无快捷键。

![面板开关](/screenshots/desktop-panel-toggle.webp)

#### 1）预览面板

在窗口右侧预览本地开发服务器（如 Vite 原型）页面，边对话边查看原型：

* 点击消息中的 localhost 链接（`localhost`、`127.0.0.1`、`[::1]`，任意端口）在面板中打开，非 localhost 链接仍用系统浏览器打开
* 消息中指向本地 `.html` / `.htm` 文件的路径也在本面板打开并渲染页面；渲染失败时回退到文件面板，本面板不提供该文件的源码视图
* 支持多标签页，同一面板内导航；dev server 热更新自动反映改动，提供绕过缓存的强制刷新与「在浏览器打开」
* **切换会话时页面保活**：切走再切回原会话，地址栏地址、页面自身状态与滚动位置原样保留，不会重新加载；同时保活的页面全局上限 4 个，超出时按最久未使用淘汰。只有在关闭该预览标签页、删除会话、关闭所在分屏或退出应用时才真正销毁——**这一点与下一小节「终端面板」正好相反**（终端 PTY 随会话切换终止）
* **全屏时对话不消失**：tab 栏右端的全屏按钮让面板铺满内容区，此时对话列缩成预览区底部居中的悬浮对话框（消息列表、任务清单与消息队列不显示，输入框与发送逻辑不变）。发送后对话框换成「正在工作」加载态，本轮结束后恢复为空白输入框；退出全屏后输入框里还没发出去的内容、对话的滚动位置都还在，光标回到输入框
* 工具栏提供**元素拾取**：悬停元素显示高亮轮廓、点击后添加评论，评论连同元素上下文追加到输入框，可连续拾取、统一编辑后一起发送（详见 [4.2 Localhost原型预览与元素评论](#_4-2-localhost原型预览与元素评论)）

![预览面板](/screenshots/desktop-preview-tabs.webp)

![预览全屏](/screenshots/desktop-preview-fullscreen.webp)

#### 2）计划面板

当 AI 制定执行计划并准备退出计划模式时（ExitPlanMode），计划全文自动展示在计划面板中（对话确认框只保留精简摘要）；也可通过 `/plan` 在会话中查看当前计划文件。计划内容按 Markdown 渲染，支持表格、代码块等。

![计划面板](/screenshots/desktop-plan-pane.webp)

#### 3）差异面板

实时查看当前对话相对仓库基线的全部改动（agent 已提交到会话分支的、工作区尚未提交的、以及尚未跟踪的新文件），不离开应用即可审查 agent 这一轮到底改了什么：

* **变更基准**：会话分支相对仓库默认分支的分叉点（`git merge-base HEAD <默认分支>`），无默认分支时退化为 `HEAD`（只看未提交改动），仓库尚无 commit 时退化为已暂存内容；工具栏只读展示 `{变更基准} → 工作树`、改动文件数与总增删统计
* **左侧栏（文件树 + 提交选择）**：按路径层级组织、目录可折叠、文件行显示 `+N −M`（完整路径在 title 中），点击文件即展开并滚动到该文件；文件树下方按新→旧列出变更基准到 `HEAD` 之间的提交（首项「全部改动」默认选中），选中某条后文件数 / 统计 / 文件树 / 内容都切到该提交自身的改动；显隐状态与所选提交随会话记忆，槽位过窄放不下文件树与可读宽度的差异区时左侧栏自动隐藏、加宽即恢复（不改写显隐记忆）
* **统一 / 并排视图**：工具栏可切换；并排视图为左旧右新两列（各带行号），配对不足的一侧补空位；切换只换排布，不重新请求数据
* **大规模差异降级**：范围内总增删超过 5000 行时默认折叠全部文件并提示「差异过大，已折叠全部文件」；单文件超过 1000 行时该文件不做词级高亮（保留行级增删底色与行评论）；单文件内容仍按 2000 行上限截断并提示
* 以手风琴形式逐文件展示：文件头部显示相对路径、状态标识（新增 / 修改 / 删除 / 重命名 / 未跟踪）与增删行统计，展开区为增删行高亮的差异内容（含词级高亮）
* 一轮生成结束后自动刷新为最新改动，也提供手动刷新；刷新期间保留现有内容直至新数据到达
* 支持在差异行上添加评论，评论追加到输入框与 agent 沟通
* 非 git 目录显示「非 git 仓库」空状态，无改动时显示「无改动」

![差异面板](/screenshots/desktop-diff-pane.webp)

![差异面板并排视图](/screenshots/desktop-diff-split.webp)

![差异行评论](/screenshots/desktop-diff-comment.webp)

#### 4）终端面板

在对话旁打开一个真正的终端，以该对话工作目录为 cwd 启动登录交互会话，无需离开应用即可验证改动或执行辅助操作：

* 真 PTY 会话，支持 vim、top 等交互式程序，按键全量透传，Ctrl+C 中断前台程序
* 输出含 ANSI 颜色正确渲染，面板宽度变化时同步重排；剪贴板与系统互通
* 取消勾选再重新勾选时，shell 会话与滚动输出原样保留；工具栏提供「重启终端」
* 终端输出中的 localhost 链接与消息一致：在预览面板打开，非 localhost 链接用系统浏览器打开
* 关闭分屏 / 删除会话 / 退出应用时终止 PTY 进程，不残留孤儿进程

![终端面板](/screenshots/desktop-terminal-pane.webp)

#### 5）文件面板

点击消息中 read / edit / write 工具的文件路径，在右上角打开文件面板查看文件内容，无需离开对话即可核对 agent 读写过的文件：

* 本地与远程（SSH）会话统一承载文件查看；本地会话额外提供「在默认应用中打开」
* 例外：本地 `.html` / `.htm` 路径优先在**预览面板**渲染页面，渲染失败才回退到本面板；本面板是「源码 / 文本」视图，不为这类文件提供源码查看入口
* 行号、长行水平滚动（行号列固定）、按扩展名语法高亮；Markdown 文件按渲染后展示，图片文件内联预览
* 带起止行信息时自动滚动定位；支持复制完整路径、复制文件内容（一颗按钮复制当前查看的整份内容，编辑态复制含未保存修改的草稿；Markdown 复制的是源文本）、面板内搜索；文件过大或二进制时截断 / 拒读并提示
* 本地会话可直接在面板里改文件：工具条「编辑」进入编辑态（带行号的编辑器），改完点「保存」或按 `⌘S` / `Ctrl+S` 写回磁盘，正文回到只读并提示「已保存」；Markdown 文件编辑的是源文本，保存后回到渲染视图
* 保存前会比对磁盘上的内容：文件已被 agent 或外部编辑器改过时不覆盖，面板提示「文件已在磁盘上更新」，由你选择「覆盖」（写入自己的版本）或「重新加载」（丢弃修改、回到磁盘内容）；写盘失败时草稿保留，可重试或取消
* 有未保存的修改时，打开另一个文件、关闭面板、切换会话或工作目录、新建 / 删除会话都会先确认是否放弃；选「继续编辑」则原操作不执行、草稿原样保留
* 远端会话的文件面板仍只读；内容被截断的超大文件、二进制与图片不提供编辑入口
* 面板内编辑面向顺手改一处，不提供多光标、查找替换、格式化等能力，重活仍用「在默认应用中打开」跳到外部编辑器；保存需手动触发（不自动保存），未保存的草稿不跨应用重启保留
* 支持在代码行上添加行评论（与差异面板同一交互）：右键某行选「添加评论」，或选中连续几行后点选区末尾浮出的按钮，在该行（或该段行）下方展开输入框，写下的评论连同文件路径、行号（或行区间）与该处内容追加到消息输入框（不直接发送，可连续评论多行后统一发给 agent）；工具条上的「评论」按钮对当前选区或最近点击过的那一行打开同一个输入框；Markdown 文件按块评论——悬停标题 / 段落 / 列表项 / 引用 / 表格单元格 / 代码块时块外侧出现「+」，追加内容带该块的文本片段、不带行号；图片不提供评论入口；编辑态下不提供评论入口
* 手动勾选「文件」面板且还没打开具体文件时，正文先列出**这次对话读写过的文件**（最近的在前，点一行即在面板内打开），不会翻消息流也能找到文件；当前对话还没有文件、也还没打开过文件时才显示「打开的文件会显示在这里」占位（正文左侧是该会话的目录树，可直接从树里点开文件）。清单来自对话本身，不列创作集（artifact 是服务端链接，没有文件与文件夹的概念）

![文件面板](/screenshots/desktop-file-pane.webp)

![文件面板编辑](/screenshots/desktop-file-pane-edit.webp)

![当前对话的文件](/screenshots/desktop-file-pane-conversation-files.webp)

![文件面板行评论](/screenshots/desktop-file-comment.webp)

![文件行评论追加到输入框](/screenshots/desktop-file-comment-input.webp)

![Markdown 块评论](/screenshots/desktop-file-md-comment.webp)

## 2. Agent核心

### 2.1 对话

#### 1）基础对话

支持 Markdown 格式的文本交互，能够生成带有语法高亮的代码块，方便用户直接阅读和复制。

![基础对话](/screenshots/desktop-basic-conversation.webp)

#### 2）AI 思考过程

对于支持推理的模型（如 DeepSeek R1, OpenAI o1），CodeWave IDE 可以展示 AI 的思考过程，让用户了解 AI 是如何得出结论的。思考过程在生成时默认展开、实时呈现，思考结束后会自动收起以保持界面整洁；用户可随时点击"思考"标题展开或收起，查看完整的推理内容。

![AI 思考过程](/screenshots/desktop-reasoning-block.webp)

#### 3）消息队列

当 AI 正在处理当前请求并进行流式输出时，用户仍然可以发送新消息。这些消息会自动进入队列，并在当前任务完成后按顺序自动执行。

主要特性：

* **忙碌时发送**：在 AI 运行时，仍可正常输入内容并按回车发送，消息会自动加入队列（此时发送按钮变为"停止"按钮，点击可中止当前任务）。
* **自动执行**：当前任务完成后，下一条排队消息会自动开始处理，无需用户手动干预。
* **队列面板**：消息队列以可折叠面板的形式固定在输入框上方，方便在消息较多时进行管理，且不会随聊天记录滚动。
* **队列顺序**：按发送先后从上到下排列，最后发送的在最下方。
* **单行展示**：每条消息占一行，过长时末尾省略，鼠标悬停可通过 Tooltip 查看完整内容。
* **总数统计**：面板标题显示队列中的消息总数，如"消息队列 (8)"。
* **展开 / 收起**：面板支持展开与收起，默认收起；收起时仅露出队列的第一条消息，展开时若超过最大高度则在面板内滚动展示。

消息操作（悬停某条消息时显示）：

* **编辑**：点击编辑图标后，该条消息内容会载入输入框进行编辑，原消息仍保留在队列中。
  * 编辑后点击发送：若原消息仍在队列中，则原位更新其内容，不影响队列顺序；
  * 若原消息已不在队列中（已被删除或已开始执行），则全局提示"编辑的队列消息已不存在！"，由用户自行决定输入框中内容的去留。
* **删除**：点击垃圾桶图标可将该条消息从队列中移除。
* **清空队列**：点击"新建对话"会同时清空当前会话和所有排队消息。注意：手动点击"停止"按钮中止当前任务时，不会清空消息队列。

![消息队列](/screenshots/desktop-message-queue.webp)

#### 4）历史提示词

支持快速搜索并重用之前的 Prompt，提高交互效率。

主要特性：

* **快捷键触发**：在输入框中按下 Ctrl+R (或 Cmd+R) 即可弹出历史提示词界面。
* **工具栏入口**：点击输入框工具栏的"+"（添加）按钮，在弹出菜单中选择"历史提示词"即可打开。
* **实时过滤**：支持按关键词实时搜索历史记录，结果按时间倒序排列。
* **键盘导航**：支持使用上下箭头键选择记录，按下 Enter 键将选中的 Prompt 填入输入框。
* **智能拦截**：当焦点在聊天输入框时，Ctrl+R 等快捷键会被 Webview 优先拦截，防止触发 VS Code 的默认行为，确保流畅的聊天体验。

![历史提示词](/screenshots/desktop-history-search.webp)

#### 5）对话回滚

支持将对话回滚到之前的任意用户消息状态。这不仅会删除该消息及其之后的所有对话记录，还会自动撤销 AI 在这些回合中所做的所有文件更改，并将被回滚的消息内容重新填充到输入框中，方便用户修改后重新发送。

主要特性：

* **悬停触发**：当鼠标悬停在历史记录中的用户消息上时，右上方会出现"回滚"图标。
* **/rewind 命令**：输入 `/rewind` 打开检查点列表面板，展示所有可回滚的用户消息，支持键盘上下导航、Enter 选择、Esc 关闭。
* **一键回滚**：点击图标并确认后，系统会自动清理后续消息、恢复文件状态，并将该消息内容回填至输入框。
* **安全确认**：执行回滚前会弹出应用内二次确认对话框（VS Code、JetBrains 与桌面应用三端样式一致），防止误操作导致数据丢失。
* **状态同步**：回滚后，任务列表、会话元数据以及输入框内容会自动同步到回滚后的状态。

![对话回滚](/screenshots/desktop-rewind-button.webp)

#### 6）会话管理与恢复

会话以 JSONL 文件保存在本地（`~/.wave/projects/`，按项目目录隔离存储），桌面端提供「侧边栏会话树」、「会话状态看板」与输入框 `/resume` 三种方式浏览并恢复历史会话。

**侧边栏会话树**：侧边栏按项目（工作目录）分组展示全部历史会话：

* **点击恢复**：点击会话卡片即可恢复该会话继续对话；若该会话属于其他项目，会先切换工作目录再恢复。
* **分屏打开**：`Cmd/Ctrl + 点击` 会话，或将会话拖入对话区域，在分屏窗格中并排展示。
* **重命名**：悬停会话条目打开行菜单（并排打开 / 重命名 / 删除会话）选「重命名」，该行标题就地变成输入框（预填并全选原标题），`Enter` 或点击别处保存、`Esc` 取消；列表不进加载态，`trim` 后为空则什么都不做。写盘失败时标题回滚为原标题，并在该行下方给出可见的失败提示。
* **删除会话**：悬停会话条目可删除该会话，关联的 worktree 与分支会一并清理。
* **列表滚动、入口固定**：会话多到一屏放不下时只有会话列表区域滚动，「新对话」「插件市场」入口与底部账户卡片始终固定可见（不随列表滚走），随时都能新建对话、进入插件市场或查看套餐用量。

![侧边栏会话行菜单](/screenshots/desktop-session-rename-menu.webp)

![侧边栏会话行内重命名](/screenshots/desktop-session-rename.webp)

**头部标题就地编辑**：分屏顶部的会话标题也能直接点击改名——标题变成输入框并全选原文，`Enter` 或点击别处保存、`Esc` 取消。改名成功后，侧边栏该行、会话看板卡片与分屏头部同时显示新标题；保存失败时回滚为原标题并给出可见提示。标题以 `custom-title` 保留条目写在会话自己的 JSONL 文件里，所以命令行、插件端与桌面端看到的是同一个标题；已设的标题不会被随后的首条消息重新推导覆盖。

**会话状态看板**：点击侧边栏顶部的会话状态按钮打开，按「等待中 / 运行中 / 已完成」三列展示全部会话：

* **项目筛选**：顶部下拉可按项目（工作目录）筛选会话。
* **状态一目了然**：等待人工确认、正在运行与已完成的会话分列展示，便于集中跟进。
* **点击恢复**：点击任意会话卡片即可恢复该会话；左侧会话列表同样可点——在看板里点一条会话直接进入它并退出看板，不必先关看板再选会话。
* **返回不丢内容**：从看板返回对话窗口，输入框里还没发出去的内容原样还在。

![会话状态看板](/screenshots/desktop-session-board.webp)

**`/resume` 会话内切换**：在输入框中输入 `/resume` 打开居中的会话选择器，直接切到另一段对话继续，不必新建对话或重启应用。列表来自**当前对话所属主机**磁盘上的全部会话——包括命令行或其它客户端创建的、桌面端从未登记过的会话——按最后活跃时间倒序排列，每行显示会话标题、项目路径与最后活跃时间，支持关键词搜索、`↑` `↓` 选择、`Enter` 确认、`Esc` 取消。

* **跨项目恢复**：选中其它项目的会话时先切换到该会话的工作目录再恢复；该会话随后登记进侧边栏会话树与状态看板，之后可从这两个入口再次进入。
* **目录已不存在**：不切换，提示该会话的目录已不存在，当前分屏与内容保持原状。
* **主机不可达**：提示无法连接主机（而不是显示空列表让用户以为没有历史会话），当前会话不受影响。
* **分屏与远程**：分屏状态下选择器同样可用，列表范围随当前焦点分屏所属主机变化（远程对话列出该主机磁盘上的会话）。

![恢复会话](/screenshots/desktop-resume-sessions.webp)

### 2.2 模型

#### 1）内置模型

| 模型              | 视觉能力 | 备注               |
| ----------------- | -------- | ------------------ |
| glm-5             | 否       |                    |
| glm-5.1           | 否       |                    |
| glm-5.2           | 否       |                    |
| glm-5-turbo       | 否       |                    |
| kimi-k3           | 是       |                    |
| kimi-k2.5         | 是       |                    |
| kimi-k2.6         | 是       |                    |
| kimi-k2.7-code    | 是       | 代码专用           |
| qwen3.5-flash     | 否       |                    |
| qwen3.7-max       | 否       |                    |
| qwen3.8-max       | 是       | 支持 promptCaching |
| qwen3.7-plus      | 是       | 保留思考过程       |
| deepseek-v4-pro   | 否       |                    |
| deepseek-v4-flash | 否       | 默认模型           |

#### 2）切换模型

输入卡片底栏左侧显示当前会话使用的模型。点它向上展开模型列表，完整列出所有已配置的模型，能读图的模型带「视觉」标识；选中即生效，此后这条会话的交互都用新模型。

![切换模型](/screenshots/desktop-model-picker.webp)

### 2.3 上下文

#### 1）查看上下文使用率

在每一轮对话结束后，对话内容的最底部会显示模型可用的上下文窗口，以及本轮对话的上下文使用率。

![上下文使用率](/screenshots/desktop-context-usage.webp)

#### 2）压缩上下文

本系统采用多层压缩机制管理对话历史，确保在长对话中不超出模型 token 限制：

* 在 AI 处理任务的过程中，当使用的上下文超过允许的上下文窗口时，系统会自动触发一次上下文压缩。
* 也可使用 `/compact` 手动压缩对话历史。
* 通过压缩上下文，你可以移除冗余信息，仅保留与当前任务相关的关键内容，从而确保 AI 聚焦于核心上下文并维持输出质量。

**自动压缩 (Auto-Compact)**

* 每次 AI 响应后记录 token 使用量（仅 `total_tokens`，缓存命中已含其中）
* 请求发出前按「最近一次响应的 `total_tokens` + 其后新增消息」估算上下文，达到自动压缩阈值（`contextWindow − min(maxOutputTokens, 20000) − 13000`）时先压缩再发
* 使用快速模型（fastModel）生成对话摘要，`max_tokens` 取全局输出上限，temperature: 0.1
* 压缩前从消息中剥离图片以降低 token 消耗
* 按 API round 边界分组消息，保留最后 2 个 API round，避免拆分 tool_use/tool_result 对
* 被压缩的消息替换为 compress 块（类型为 compress，内容为摘要文本）
* compress 块在发送 API 请求时转换为 user 角色消息
* 压缩后创建新会话，通过 parentSessionId 链接到旧会话，保持历史可追溯
* 递归压缩时，旧摘要连同整个历史被新摘要替换

**熔断机制 (Circuit Breaker)**

* 跟踪连续压缩失败次数
* 连续 3 次失败后跳过压缩并记录警告，避免在损坏的上下文中浪费 API 调用
* 压缩成功后失败计数器重置为 0

**压缩后上下文恢复 (Post-Compact Context Restoration)**

* 最近读取的文件：最多 5 个文件，每个 5000 tokens
* 当前工作目录路径
* 计划模式状态及计划文件路径
* 已调用的 Skill 列表（名称和描述，总预算 25k tokens，单个 5k）
* 后台子代理的描述和运行状态
* 上述内容以 \[Context Restoration] 章节追加到摘要末尾

![上下文压缩按钮](/screenshots/desktop-compress-button.webp)

### 2.4 代码理解与操作

#### 1）终端工具

AI 可以执行终端命令，命令结束后展示完整输出，帮助用户完成自动化任务、运行测试或安装依赖。

![嵌入式终端面板](/screenshots/desktop-terminal-pane.webp)

![对话级面板开关](/screenshots/desktop-panel-toggle.webp)

#### 2）文件搜索与探索

AI 可以使用多种工具来探索项目代码库，这些工具的执行过程和结果都会以直观的工具块形式展示，并在标题栏显示关键参数（Compact Parameters）：

* **Task (Explore)**：启动专门的子代理进行深度探索，标题显示任务描述（如 `Explore: 查找所有 API 定义`）
* **Glob**：按模式搜索文件，标题显示搜索模式和路径（如 `src/**/*.ts in src`）
* **Grep**：在文件中搜索文本内容，标题显示搜索模式、文件类型和路径（如 `interface.*API ts in src`）
* **Read**：读取文件内容，标题显示文件路径及读取范围（如 `src/main.ts 1:2000`）

![文件搜索与探索](/screenshots/desktop-exploration.webp)

#### 3）文件操作工具

除了基础的编辑，AI 还可以执行更复杂的文件操作，并以直观的方式呈现操作的文件路径与内容：

* **Write**：创建新文件并写入内容，以纯内容预览的形式呈现——标题显示可点击的文件路径（如 `Write src/new-file.ts`，点击即在编辑器中打开该文件），并附带行数与字符数统计（如 `18 行 · 512 字符`）；下方是可滚动的内容预览区，超出高度部分以底部渐变提示，将鼠标悬停在预览区右上角可点击放大按钮打开完整文件
* **Edit**：在文件中进行精确的字符串替换，标题显示文件路径（如 `src/app.tsx`），并以 Diff 视图展示前后变化

![文件操作工具](/screenshots/desktop-file-ops.webp)

#### 4）文件差异对比

当 AI 建议修改文件时，会通过直观的 Diff 视图展示更改内容，用户可以清晰地看到每一行代码的变化。

![差异面板](/screenshots/desktop-diff-pane.webp)

![差异行评论](/screenshots/desktop-diff-comment.webp)

![差异评论输入](/screenshots/desktop-diff-comment-input.webp)

#### 5）LSP 代码智能

CodeWave IDE 集成了 Language Server Protocol (LSP)，使 AI 能够像 IDE 一样理解代码。工具标题会显示具体的操作和位置（如 `goToDefinition src/main.ts:10:5`）：

* **Go to Definition**：查找符号定义
* **Find References**：查找所有引用
* **Hover**：获取类型信息和文档
* **Call Hierarchy**：分析函数调用链

![LSP 代码智能](/screenshots/desktop-lsp.webp)

#### 6）视觉理解

当用户上传图片后，AI 可以识别图片中的 UI 设计、架构图或错误截图，并结合代码提供针对性的建议。

![视觉理解](/screenshots/desktop-vision.webp)

### 2.5 权限与安全

#### 1）权限模式管理

提供五种权限管理模式，用户可以根据需要灵活切换：

* **默认模式（修改前询问）**
  * 在默认模式下，AI 执行任何涉及文件修改或系统操作的工具之前，都会先向用户请求确认。这是最安全的模式，适合初次使用或处理重要项目时使用。
* **自动接受修改模式**
  * 在此模式下，AI 可以自动执行文件编辑、创建和删除操作，无需每次确认。适合在信任 AI 建议且希望提高效率的场景下使用。
* **计划模式**
  * 计划模式是一种特殊的工作模式，AI 只能修改计划文件（通常是 `.wave/plans/` 目录下的文件），用于协作制定和完善开发计划，而不会直接修改项目代码。这种模式特别适合项目规划阶段。
* **完全跳过权限模式（bypassPermissions）**
  * 最高权限模式，完全跳过所有权限检查，所有工具无需确认直接执行。仅在完全受控环境中使用。
* **安全区域（Safe Zone）**
  * 用户可通过 settings.json 中的 `permissions.additionalDirectories` 配置，将额外目录纳入安全区域。在安全区域内的文件操作可被自动接受，无需逐次确认。

![安全区域配置案例](/screenshots/desktop-safe-zone.webp)

特点：

* **下拉切换**：点击输入框左下角的权限模式按钮即可弹出下拉菜单切换模式
* **视觉区分**：每种模式都有不同的图标和颜色标识
* **实时生效**：切换后立即应用到当前会话中

![权限模式下拉菜单](/screenshots/desktop-permission-mode.webp)

#### 2）代码修改确认

在进行代码编辑、文件写入或删除操作前，系统会显示具体的修改内容供用户确认。

主要特性：

* 显示文件路径和修改的具体内容
* 集成差异对比器显示代码变更
* 支持批准单次修改或设置自动批准规则
* 提供反馈机制让用户指导修改方向

![代码修改确认](/screenshots/desktop-edit-confirm.webp)

#### 3）命令执行确认

执行系统命令前会显示具体的命令内容，确保用户了解将要执行的操作。

主要特性：

* 清晰显示即将执行的 Bash 命令
* 提供命令描述和执行目的说明
* 支持单次批准或设置持久化规则
* 可按命令前缀或具体命令设置自动批准

![命令执行确认](/screenshots/desktop-bash-confirm.webp)

#### 4）MCP 工具确认

当 AI 调用通过 MCP（Model Context Protocol）连接的外部服务工具时，确认框会展示该工具的完整参数，让用户了解即将传递给 MCP 服务器的数据。

主要特性：

* **参数展示**：以格式化的 JSON 显示 MCP 工具的全部输入参数，方便用户审核。
* **持久化规则**：支持为特定 MCP 工具设置"不再询问"规则（按工具名匹配，如 `mcp__wave_requirements__create_requirement`）。
* **反馈机制**：支持用户拒绝并提供反馈，指导 AI 调整参数后重新调用。

![MCP 工具确认](/screenshots/desktop-mcp-confirm.webp)

#### 5）计划执行确认

当 AI 制定了详细的执行计划并准备退出计划模式时，会向用户展示计划内容并请求确认。用户可以选择批准执行、自动接受后续修改，或提供反馈意见。

主要特性：

* 清晰显示完整的执行计划内容
* 支持 Markdown 格式的计划展示
* 提供"批准并继续"和"批准并自动接受后续修改"选项
* 支持用户反馈和计划修改建议

![计划执行确认](/screenshots/desktop-plan-confirm.webp)

#### 6）进入计划模式确认

当 AI 判断当前任务较为复杂时，会主动请求用户确认是否进入计划模式。与计划执行确认不同，进入计划模式确认仅提供两个选项：批准进入计划模式，或拒绝并直接开始实现。

主要特性：

* **简洁选项**：仅显示"批准并继续"和"不，现在开始实现"两个按钮，匹配 Claude Code 的交互风格。
* **无"不再询问"选项**：不会显示持久化权限选项，确保每次计划模式转换都需要用户明确确认。
* **无反馈输入**：不提供反馈输入框，用户只能选择批准或拒绝。
* **无计划预览**：此确认不展示计划内容（计划内容仅在退出计划模式时展示）。
* **权限模式切换**：批准后，会话权限模式自动切换为 plan 模式。
* **拒绝处理**：拒绝后，AI 收到"不，现在开始实现"的反馈消息，直接开始执行任务。

![进入计划模式确认](/screenshots/desktop-enter-plan-mode.webp)

#### 7）交互式提问

当 AI 需要更多信息或需要用户做出决策时，会通过交互式表单向用户提问。用户回答后，问题与答案将以垂直布局展示，确保在窄屏下也能清晰阅读。

主要特性：

* **单选与多选**：支持单选（Radio）和多选（Checkbox）两种模式，选中项以高亮背景标识。
* **多个问题分页**：当一次提出多个问题时，标题右侧提供 `< N / M >` 分页导航，逐题作答；底部提供"下一个"与"提交回答"按钮。
* **自定义回答**：每个问题均附带"其他"选项，可输入自定义内容，输入框随内容自动撑高（超出上限后内部滚动）。
* **选项区可折叠**：弹窗右上角的折叠键可收起全部选项与"其他"输入框，题干、题号进度与底部按钮留在原位；再次展开后已选答案、草稿、当前题号与滚动位置都保留。该折叠键只出现在本提问弹窗上，命令执行、文件写入等审批弹窗没有。

![交互式提问](/screenshots/desktop-ask-user.webp)

### 2.6 任务管理

#### 1）任务列表

AI 会根据任务目标自动规划并管理任务列表，实时展示任务进度（待办、进行中、已完成、已删除）以及任务间的依赖关系。任务列表固定在输入框上方，随任务状态实时更新，支持折叠以节省空间。

任务列表相关工具（TaskCreate / TaskGet / TaskUpdate / TaskList）默认关闭。需要时在设置文件的 `env` 块里设置 `"WAVE_ENABLE_TASK_TOOLS": "1"`（或启动进程前导出同名环境变量），保存后自动生效，无需重启会话；置为 `"0"` 或不设置即关闭。任务列表界面与后台任务通知不受该开关影响，关闭时任务列表只为空。

主要特性：

* **固定在输入区上方**：任务列表始终展示在输入框上方，不随消息流滚动，便于随时查看整体进度。
* **可折叠设计**：点击任务列表 Header（显示任务计数）即可在展开和折叠状态间切换。
* **状态指示**：Header 的 Chevron 图标直观展示当前折叠状态，每个任务行前的图标展示其状态。

#### 2）后台任务通知

当后台任务（如 Shell 命令或子代理）完成执行时，CodeWave IDE 会在聊天消息中显示任务通知块，告知用户任务的状态和结果摘要。

主要特性：

* **状态指示**：通过不同的图标和颜色直观展示任务状态——绿色对勾表示已完成，红色叉号表示失败，灰色斜杠表示已终止。
* **任务摘要**：简洁地展示任务的执行结果，如测试通过情况或代理错误信息。
* **输出文件链接**：如果有输出文件，会显示文件路径方便用户查看。

![后台任务通知](/screenshots/desktop-background-notification.webp)

#### 3）后台任务系统

CodeWave IDE 支持前台和后台两种任务执行模式：

* **Foreground Task**：前台执行的任务（如正在进行的 Bash 命令），用户可将其退化为后台
* **Background Task**：后台执行的任务，包括：
  * shell 类型：后台 Bash 命令（run_in_background: true）
  * subagent 类型：后台子代理
* 状态流转：running → completed/failed/killed
* Notification Queue：后台任务完成后自动将通知注入聊天消息，显示任务状态和结果摘要
* 支持 TaskStop 工具通过 task_id 中止指定后台任务

#### 4）后台任务管理对话框

输入 `/tasks` 斜杠命令可打开后台任务管理对话框，集中查看与管理当前会话中的所有后台任务（包括 shell、subagent、workflow 三种类型）。任务列表会随后台状态实时更新（由扩展通过 updateBackgroundTasks 推送）。

**列表视图：**

* 每行展示任务标识 `[id] type`，并通过彩色圆点指示状态——绿色 running、蓝色 completed、红色 failed、黄色 killed。
* 显示任务描述、执行的命令（`$ <command>`）、启动时间、运行时长以及退出码（若已结束）。
* 处于 running 状态的任务行提供「停止」按钮，点击后向扩展发送 stopBackgroundTask，按钮临时切换为「停止中...」。

**详情视图：**

* 点击列表中的任意任务进入详情，展示完整的运行信息：标识、类型、状态（含退出码）、描述、命令、启动时间与运行时长、日志文件路径（Log）。
* 底部展示「OUTPUT (last 20 lines)」区域，按需通过 getBackgroundTaskOutput 拉取任务的标准输出末尾 20 行；若存在标准错误输出，则额外展示「ERRORS」区域。
* 运行中的任务提供「停止」按钮。
* 交互：点击遮罩层外部或按 Esc 关闭对话框；在详情视图按 Esc 先返回列表。底部按钮：「返回列表」（仅详情视图可见）与「关闭」。空列表时显示「暂无后台任务」。

![后台任务管理对话框](/screenshots/desktop-background-tasks.webp)

### 2.7 多Agent与并发

#### 1）Agents 对话框

输入 `/agents` 斜杠命令可唤起设置页并选中「子代理」选项卡，查看当前会话中所有可见的子代理（subagent）定义。定义按来源分组展示——内置 agents、用户 agents、项目 agents、插件 agents，数据由扩展通过 getSubagentConfigurations 从 CLI 实时获取。

**列表视图：**

* 每个分组以来源名开头（内置 / 用户 / 项目 / 插件），组内每行展示代理名称、模型（`· <model>`）与描述。
* 插件提供的代理以 `插件名:代理名` 的命名空间形式展示，避免与内置或用户代理重名。
* 点击任意行进入详情。

**详情视图：**

* 展示完整配置：描述、模型（未显式配置时显示「默认（未显式配置）」）、来源、可用工具、定义文件路径与系统提示词全文。
* 系统提示词以代码块展示，内容过长时在对话框内部滚动。

#### 2）并发使用子代理

AI 可以在同一回合内并行启动多个 Agent 工具块（并发安全的工具会批量并行执行），消息流中会实时显示各个子代理的进度。主要有两种使用方式：

**方式一：工具块内直接并发**

在一条消息中要求 AI 同时完成多件事，AI 会并行启动多个子代理。提示词示例：

> 请同时做三件事：1) 梳理支付模块的代码结构；2) 审查分布式事务中的竞态条件；3) 盘点测试覆盖缺口。

**方式二：后台运行子代理**

要求 AI 使用 run_in_background 参数把子代理放入后台执行，不阻塞当前对话——主对话可以继续做其他事，子代理完成后会收到任务通知，也可通过 `/tasks` 命令集中管理。

提示词示例：

> 在后台调研支付网关的兼容性，同时并行审查提现流程的边界条件，我们先继续重构其他模块。

![并发使用子代理](/screenshots/desktop-subagent-concurrency.webp)

#### 3）并排多对话

1. 拖拽左侧会话树到对话区域，或者 Cmd/Ctrl+点击会话，新增一个分屏并排展示会话。
2. Cmd/Ctrl+Shift+N（macOS 为 Cmd+Shift+N）一步并排打开空白新会话；Cmd+W 关闭当前分屏（仅剩一个时不提供关闭入口）。

* 各分屏的消息流、流式状态、任务列表与确认交互互不影响，多个分屏可同时流式生成；关闭正在生成的分屏后会话在后台继续运行（侧边栏运行中标识保留）
* 拖拽分屏头部可重排左右顺序，拖拽分屏间的分隔条可调整宽度（最小 360px）；手动调过的宽度比例在新增/关闭分屏时按比例保持
* 横向空间拥挤时，把分屏拖到聊天区上/下边缘可形成上下两行分屏（最多两行），利用垂直空间对照更多会话；拖拽行间分隔条调整行高（最小 280px），把下行分屏拖回上行即消除空行

![并排多对话](/screenshots/desktop-split-panes.webp)

### 2.8 SubAgent

子代理（SubAgent）是把任务委派给具有独立上下文、专业角色和工具权限的专用 Agent 执行。有三种使用方式：

#### 1）内置的子代理

| 子代理          | 文件名             | 描述                                                                  | 工具                                               | 模型        | 备注                                                                                                                   |
| --------------- | ------------------ | --------------------------------------------------------------------- | -------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| Explore         | explore.md         | 只读的代码定位代理：按模式找文件、检索符号/关键词、回答「X 定义在哪」 | 除 Agent/Artifact/ExitPlanMode/Edit/Write 之外全部 | inherit     | 不用于 code review、设计文档审计、跨文件一致性检查或开放式分析；跳过项目 AGENTS.md；按 quick/medium/very thorough 检索 |
| Plan            | plan.md            | 软件架构师：设计实现方案，产出分步计划、关键文件、架构权衡            | 与 Explore 相同（黑名单）                          | inherit     | 只读模式；跳过项目 AGENTS.md；输出必须以 "Critical Files for Implementation"（3-5 个文件）结尾                         |
| vision          | vision.md          | 图像识别专家，运行在 WAVE_VISION_MODEL 指定的视觉模型上               | Read                                               | visionModel | 仅当主模型声明 `"vision": false` 且设置了 env 时可用；通过 `[Image source: <path>]` 元数据委托读图                     |
| general-purpose | general-purpose.md | 通用代理：复杂问题研究、代码搜索、多步骤任务执行                      | 全部（默认）                                       | 默认        | 无 name 字段，由解析器回退取文件名（subagentParser.ts:137）；可写文件但默认不建文档                                    |

#### 2）自动委派（无需手动操作）

当你描述任务时，我会自动判断是否匹配某个子代理的专业方向并委派。例如：

* 搜索代码 → 自动派 Explore 子代理
* 设计实现方案 → 自动派 Plan 子代理
* 研究复杂问题 → 自动派 general-purpose 子代理

![自动委派子代理](/screenshots/desktop-subagent.webp)

#### 3）显式点名（精确控制）

在输入框敲 `@`，候选列表除文件外还列出当前会话可见的子代理（名称 + 描述），选中即插入 `@<名称>` 标签，发送后排给该子代理执行：

* 候选按名称或描述过滤，子代理条目排在文件之前
* 一条消息可点名多个子代理
* 也可以直接手打或粘贴 `@<名称>`；名字没加载时，主对话会收到可用子代理清单

在需求中直接说明同样有效，例如：

* "用 Explore 子代理找到所有 API 入口"
* "让 Plan 子代理先出一份迁移方案"
* "派多个子代理分别调研这三种方案的优劣"

![显式点名子代理](/screenshots/desktop-subagent.webp)

#### 4）创建自定义子代理（团队沉淀）

在项目目录 `.wave/agents/`（或用户级 `~/.wave/agents/`）下放一个 Markdown 文件即可：（也可通过 设置-子代理-创建子代理，快速创建子代理）

```markdown
---
name: testing-expert
description: 测试专家，负责编写与审查测试用例
tools: [Read, Bash, Glob]
model: fastModel
---

你是一名测试专家。你的职责：

1. 分析代码的可测试性并指出薄弱点
2. 按项目规范编写单元测试与集成测试
3. 运行测试并修复失败用例
```

* **name**：唯一标识
* **description**：描述专长与适用场景（用于自动匹配）
* **tools**：限定可用工具（只给必要的）
* **disallowedTools**：工具黑名单（内置 Explore/Plan 就用它，除 Agent、Artifact、ExitPlanMode、Edit、Write 之外全部可用）；与 `tools` 同时写时以 `tools` 为池、再减掉黑名单，两个列表里都出现的工具一律不可用
* **model**：可选，指定专用模型（fastModel/visionModel 可解析对应环境变量，inherit 表示跟随主对话模型）
* **omitAgentsMd**：可选，设为 `true` 时该子代理不注入项目 `AGENTS.md`（及 `CLAUDE.md` 回退）、用户记忆与 `.wave/rules` 无条件规则；Claude Code 的写法 `omitClaudeMd` 同样识别
* **isolation**：可选，设为 `worktree` 时每次调用都在独立临时工作树中执行

![子代理设置页](/screenshots/desktop-settings-subagents.webp)

#### 5）子代理可使用的模型

**特殊值（推荐）**

| 写法               | 解析为            | 当前值            |
| ------------------ | ----------------- | ----------------- |
| model: inherit     | 主对话当前模型    | （随主模型）      |
| model: fastModel   | WAVE_FAST_MODEL   | deepseek-v4-flash |
| model: visionModel | WAVE_VISION_MODEL | qwen3.7-plus      |
| 不写 model         | 默认模型          | deepseek-v4-flash |

**具体模型 ID（全部可选）**

* glm-5 / glm-5.1 / glm-5.2 / glm-5-turbo
* kimi-k3 / kimi-k2.5 / kimi-k2.6 / kimi-k2.7-code（代码专用）
* qwen3.5-flash / qwen3.7-max / qwen3.8-max（支持缓存）/ qwen3.7-plus（视觉）
* deepseek-v4-pro / deepseek-v4-flash

需要注意：视觉模型只有在配置了 WAVE_VISION_MODEL 时才可用；如果某个模型 ID 不在上述列表（远程配置未下发），子代理定义会加载失败。

### 2.9 技能

技能（Skills）是封装领域知识、工具和操作流程的可复用能力包，让 Agent 在特定任务上按规范流程工作。

#### 1）使用方式

**AI 自动调用**

描述任务时，我会根据技能的 description 自动匹配合适的技能并加载其操作规范。例如：

* 你说"把这段模糊需求整理成规格文档" → 自动调用 SDD 插件的 specify 技能（内置插件，需先在「设置 → 项目设置」启用 SDD）
* 你说"做一个分享海报" → 自动调用 frontend-design
* 你说"帮我改这份 .docx" → 自动调用 document-skills:docx

**显式点名 / 斜杠命令**

在需求中直接指定技能名，或用 `/技能名` 直接触发，例如：

* "用 docx 技能把这个文档转成带修订的版本"
* 输入 `/loop 5m 检查服务状态` 触发循环技能

![技能调用](/screenshots/desktop-skill.webp)

#### 2）创建自定义技能

技能就是一个带 SKILL.md 的文件夹，放入 `.wave/skills/`（项目级）或 `~/.wave/skills/`（用户级）：（也可通过 设置-技能-创建技能，快速创建用户级/项目级技能）

例如：

```markdown
---
name: html-prototype
description: 生成单文件 HTML 原型
---

根据用户描述生成一个可交互的单文件 HTML 原型，直接输出完整代码。
```

保存后即可被自动匹配，或通过 `/html-prototype` 直接调用。

关键点：

* **匹配靠 description**：描述写得越精准，自动调用越准
* **技能可叠加**：如 SDD 先出规格 → frontend-design 再实现
* **支持 bash 插值**：技能内容里可用 `!cmd` 嵌入实时命令输出

![技能设置页](/screenshots/desktop-settings-skills.webp)

#### 3）内置 SKILL

| 技能        | 用途                                                |
| ----------- | --------------------------------------------------- |
| artifact    | 将本地 HTML/Markdown 发布为可分享网页               |
| code-review | 审查当前 diff，按力度找正确性 bug 与简化机会        |
| init        | 分析代码库并生成 AGENTS.md 指导后续 Agent           |
| loop        | 定时循环执行指令（/loop 5m /foo）                   |
| settings    | 管理 Wave 配置（settings.json、hooks、MCP、插件等） |
| simplify    | 审查并直接修复代码的复用/简化/效率问题（不找 bug）  |

### 2.10 记忆

#### 1）AGENTS.md 文件

使用 AGENTS.md 文件作为持久化的项目级和用户级指令，帮助 AI 在不同会话间保持一致的行为和上下文：

* **项目级**：`[project-root]/AGENTS.md`，存放在项目根目录，随代码库共享给所有协作者
* **子目录级**：仓库里任意子目录下的 `AGENTS.md`（如 `packages/api/AGENTS.md`），在 AI 读取该目录下的文件时按需注入——由项目根方向往里、逐层带上，项目根自身的那份仍按「项目级」常驻，不重复注入；同目录下同时存在 `AGENTS.md` 与 `CLAUDE.md` 时只取前者
* **用户级**：`~/.wave/AGENTS.md`，存放在用户全局目录，跨所有项目生效
* 内容在每次会话加载时自动注入系统提示词，确保 AI 始终遵循这些指令
* 与自动记忆系统互补：AGENTS.md 侧重长期稳定的项目指南和约定，自动记忆侧重会话过程中动态积累的项目洞察
* 自动记忆提取时会避免与 AGENTS.md 内容产生重复

#### 2）自动记忆系统 (Auto Memory)

系统在后台自动维护项目记忆，帮助 AI 持续了解项目演变：

* 每 N 轮对话触发一次记忆提取（autoMemoryFrequency 配置，默认每 1 轮）
* 使用 general-purpose 子代理在后台异步执行，不影响主对话
* 自动检测 AI 是否已手动更新记忆目录下的文件，若有则跳过避免重复
* 提取代理仅允许写入记忆目录，使用快速模型，最多 5 轮，越权写入自动拒绝
* 支持 autoMemoryEnabled 开关（默认开启）
* 记忆文件存储在 `~/.wave/projects/{项目编码}/memory/` 目录，确保 git worktree 间共享同一记忆；其中的 `MEMORY.md` 是索引，容量上限与写入提醒见[功能规格说明：记忆管理](/specs/core/memory-management)

#### 3）记忆规则

记忆规则提供上下文特定的行为指南，确保 AI 在不同场景下遵循预期模式：

* 存放在 `.wave/rules/` 目录下的多个独立 .md 文件（项目级）和 `~/.wave/rules/`（用户级）
* 支持子目录递归扫描和符号链接跟随
* 每个文件是一个独立规则，支持 YAML frontmatter：
  * **paths**：glob 模式数组，仅当相关文件在上下文中时规则才激活（空则始终激活）
  * **priority**：优先级数字，控制冲突时的覆盖顺序
* 项目规则可覆盖用户规则

### 2.11 工作流（WorkFlow）

#### 1）如何使用

工作流脚本规定"谁在何时做什么"，结果确定、可复现、断点续跑，适合大批量、多阶段的确定性任务。

使用方式：

* 直接在对话中描述任务即可，例如：
  * "用工作流对这两个模块做并行代码审查"
  * "编排一个工作流：先扫描所有接口，再逐个迁移，最后验证"
  * "用多代理工作流调研并对比这三种方案"
* 系统会把任务拆成脚本执行，运行进度可实时查看，完成后汇总结果。

#### 2）工作流管理

| 操作      | 方式                                                                                              |
| --------- | ------------------------------------------------------------------------------------------------- |
| 创建/启动 | 对话中要求"用工作流执行××"；或复用已保存脚本（scriptPath）重新运行                                |
| 查看进度  | /workflows 命令实时查看；按 phase 分组展示进度                                                    |
| 后台运行  | 启动即返回任务 ID，完成时自动通知，不阻塞其他工作                                                 |
| 停止      | 停止对应后台任务即可中断                                                                          |
| 断点续跑  | 从 runId 恢复（resume）：未修改的前缀子代理结果直接从缓存回放，只重跑变更之后的部分，省时省 token |
| 复用/迭代 | 修改 script.js 后重新运行，实现"改一版跑一版"                                                     |
| 预算控制  | 脚本可设 token 预算（budget），超限自动降级                                                       |

**典型管理场景**

* **跑挂了恢复**：工作流中断后说"从上一次运行继续"，自动跳过已完成部分
* **调整后再跑**：改脚本参数（如缺陷清单、目标文件）后重跑
* **审查消耗**：通过 /workflows 查看每次运行的 token 消耗，避免超预算

![工作流管理](/screenshots/desktop-workflow-manager.webp)

## 3. 自动化

### 3.1 钩子（Hooks）

钩子（Hooks）是把自动化脚本挂在 Wave 生命周期事件上：事件触发时自动执行命令，实现"无需人工干预的自动化"。配置在 settings.json 的 hooks 字段，修改后实时生效。

#### 1）支持的事件

| 事件名称          | 触发时机                                                         |
| ----------------- | ---------------------------------------------------------------- |
| PreToolUse        | 工具执行前（可用于校验、拦截或预处理）                           |
| PostToolUse       | 工具执行完成后（可用于后处理或日志记录）                         |
| UserPromptSubmit  | 用户提交 Prompt 时                                               |
| PermissionRequest | Wave 请求工具权限时                                              |
| Stop              | Wave 完成响应周期（无更多工具调用）时                            |
| SubagentStop      | 子代理完成响应周期时                                             |
| WorktreeCreate    | 创建新 worktree 时                                               |
| WorktreeRemove    | 删除 worktree 之前触发（通知型，非阻塞，可读取 worktree 内文件） |
| SessionStart      | 会话开始时（来源：startup/resume/compact）                       |
| SessionEnd        | 会话结束时（来源：exit/stop/compact）                            |
| CwdChanged        | 工作目录变化时（如进入/退出 worktree，非阻塞）                   |
| PreCompact        | 压缩前触发（stdout 作为附加指令合并进压缩 prompt）               |
| PostCompact       | 压缩完成后触发（接收压缩摘要文本）                               |

#### 2）配置结构

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"项目规范：原型必须单文件 HTML，主色 #4A90D9，端口 8899\"}}'",
            "description": "会话启动时注入项目规范"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "command": "echo \"[$(date)] Write tool: $(cat | jq -r '.tool_input.file_path')\" >> /tmp/hooks.log",
            "description": "记录每次文件写入"
          }
        ]
      }
    ]
  }
}
```

要点：

* **模式匹配**：支持通过 matcher 匹配工具名（如 Write、Read\*、/^Edit/），适用于 PreToolUse、PostToolUse 和 PermissionRequest。
* **异步执行**：支持 async 字段配置后台异步执行，避免阻塞工作流。
* **超时控制**：支持 timeout 字段设置最大执行时间（默认 600 秒）。
* **退出码控制**：0=成功继续；2=阻塞错误，阻止操作；其他=非阻塞错误，继续但显示警告。
* **输入上下文**：Wave 通过 stdin 向钩子进程传递 JSON 格式的详细信息。
* **热加载**：配置文件修改后即时生效，无需重启 Wave。

**退出码控制行为**

* 0：成功，正常继续
* 2：阻塞错误（PreToolUse 会阻止工具执行并反馈；UserPromptSubmit 会拦截该消息）
* 1：非阻塞警告，继续执行

**配置位置**

* 项目级 `.wave/settings.json`（团队共享）
* 用户级 `~/.wave/settings.json`（个人习惯）
* 本机覆盖 `.wave/settings.local.json`（不提交 git，适合个人机器专属钩子）

![钩子设置页](/screenshots/desktop-settings-hooks.webp)

### 3.2 定时循环任务（loop）

`/loop` 是定时循环执行指令的命令：间隔到达时自动再次执行，适合轮询、监控、定期检查。

#### 1）基本用法

`/loop [间隔] <要执行的指令>`

* 间隔格式：5m（分钟）、2h（小时）、1d（天），最小粒度 1 分钟；不写间隔默认 10 分钟。

三种写法（自动解析）：

| 写法                     | 解析结果                         |
| ------------------------ | -------------------------------- |
| /loop 5m /check          | 前导间隔 → 每 5 分钟执行 /check  |
| /loop 检查部署 every 20m | 尾部 every 从句 → 每 20 分钟执行 |
| /loop 检查部署           | 默认 → 每 10 分钟执行            |

实际示例：

* `/loop 5m 检查 http://127.0.0.1:8899 是否正常返回，异常时报告`
* `/loop 30m /standup 1`
* `/loop 1h 检查是否有新的失败测试`
* `/loop 检查磁盘空间`（默认 10 分钟）

#### 2）执行行为

* **立即执行一次**：安排后马上先跑一遍，不等第一个周期
* **周期触发**：按 cron 表达式循环，每次在 Wave 空闲时执行
* **7 天自动过期**：到期前最后执行一次后自动删除
* **随时取消**：告诉我要取消，会返回 job ID 用 CronDelete 删除

#### 3）注意事项

* 间隔会转为 cron 表达式；无法整除的间隔（如 7 分钟）会自动就近取整并告知你
* 避免整点/半点（:00/:30）触发，除非你指定精确时刻
* 循环只在本会话有效，退出 Wave 即停止（如需持久化可设置 durable）

## 4. 编程辅助

### 4.1 SDD

CodeWave IDE 随 SDK 内置了「规格驱动开发」（SDD）插件，帮助团队在写代码之前先用功能规格说明（用户故事 + 验收场景）明确设计。该插件默认关闭，不干扰日常使用。启用方式有两种：

* **设置页**：输入 `/config` 打开设置页，切换到"项目设置"选项卡，打开「SDD」开关（写入项目 .wave/settings.json；变更不会自动生效，桌面端会弹「插件已变更，重新加载后生效」，点「立即重新加载」即可让它生效——不重启对话、不打断正在生成的回复；点「稍后」则在对话框里输入 `/reload-plugins` 随时补上）。
* **配置文件**：在项目或全局的 enabledPlugins 配置中设置：

```json
{
  "enabledPlugins": {
    "sdd@builtin": true
  }
}
```

启用后，插件提供三项能力：

* **规格编写（自动触发）**：当用户提出新的需求、修改需求或涉及功能边界时，AI 会自动创建或更新对应的功能规格说明文件，自动探测项目的 docs/specs/ 或 specs/ 目录并沿用既有分组约定。该技能由 AI 自动触发，不出现在斜杠命令列表中；不明确的关键决策会以「待澄清」标记向用户提问，确认后再更新文件。
* **会话引导**：每次会话开始时，自动注入"先更新规格、确认后再实现"的流程指引，提醒需求变更时优先维护规格说明。
* **规格校验**：内置校验脚本（spec-count.js）可统计规格目录下的用户故事与验收场景数量，并对缺少必要章节的文件输出警告，方便在提交前快速检查规格完整性。启用 SDD 插件后，该校验命令在默认权限模式下自动放行（实例级允许规则 Bash(node *spec-count.js*)，锚定脚本文件名、兼容不同安装路径），只读校验不打断规格优先工作流，也无需手写随路径变化的权限规则。

![SDD 工作流](/screenshots/desktop-sdd-workflow.webp)

### 4.2 Localhost原型预览与元素评论

让 agent 启动本地开发服务器（如 Vite 原型）后，点击消息中的 localhost 链接（localhost、127.0.0.1、\[::1]，任意端口）会在窗口右侧打开预览面板，而不是跳转外部浏览器 —— 边对话边看原型：

* 非 localhost 的 http(s) 链接仍用系统默认浏览器打开
* 面板工具栏提供：地址显示、元素拾取开关、刷新、「在浏览器打开」、关闭；面板宽度可拖拽调整
* 再点击其他 localhost 链接会在同一面板内导航；dev server 热更新会自动反映 agent 的改动

点击工具栏左侧的「元素拾取」开关进入拾取模式：鼠标悬停的元素显示高亮轮廓，页面自身的点击、跳转、表单提交会被拦截：

* 点击目标元素后，旁边弹出评论卡片，写下要改什么，回车或点击右下角的添加图标把这条评论连同元素上下文追加到下方的输入框；点击卡片外空白处可取消并重新选择
* 处于禁用状态的元素（`disabled` 的表单控件、`fieldset[disabled]` 内的控件、标了 `aria-disabled` 的行）同样可以点选评论，行为与可交互元素一致（命中禁用控件内部的子元素时，以该子元素为评论目标，与悬停高亮一致）
* 评论不会立刻发送给 agent，而是追加到消息列表下方的输入框，方便你连续拾取多个元素、逐条积累评论后统一编辑、一起发送。拾取模式保持开启，可以继续点选下一个元素；提交内容包含页面 URL、元素 CSS 选择器、元素摘要与你的评论文本，agent 据此精确理解「指的是哪里」并修改原型。再次点击拾取开关退出拾取；页面导航或刷新后拾取自动重置为关闭
* 预览全屏时照样可以拾取元素：评论追加进底部悬浮的那个对话框，不用先退出全屏

![多标签预览面板](/screenshots/desktop-preview-tabs.webp)

![预览全屏](/screenshots/desktop-preview-fullscreen.webp)

预览面板全屏时页面占满内容区，对话列缩成底部悬浮的对话框，元素拾取照常可用：全屏下提交一条元素评论，面板**不退出全屏**，评论追加进那个浮卡并自动聚焦，可以接着拾取下一个元素——多次拾取的评论按顺序累积在同一个输入框里，统一编辑后一起发送；发送后浮卡显示「正在工作」，这一轮结束后恢复为空白输入框。

![全屏预览下的元素评论](/screenshots/desktop-preview-comment-floating-dialog.webp)

![全屏预览下的「正在工作」](/screenshots/desktop-preview-floating-working.webp)

### 4.3 Artifacts产物分享

Artifact：把本地 HTML 或 Markdown 文件发布成一个可分享的网页链接，一键生成、可更新、默认私有。

1. **通过意图表达触发**，如：
   * "把这个 HTML 发布成一个网页，给我链接"
   * "把这份 Markdown 做成可分享的网页"
   * "把刚才的报告生成一个网页链接，发到群里"
   * "把迁移计划做成网页形式"
2. **通过 /artifacts 命令触发**

发布成功后，可在浏览器顶部设置分享条件。

## 5. 扩展

### 5.1 MCP

#### 1）配置MCP

**路径一：界面配置（推荐）**

打开 CodeWave IDE，进入 设置 → MCP，点击添加 MCP 服务；保存后自动连接，服务器列表显示连接状态。

![MCP 设置页](/screenshots/desktop-settings-mcp.webp)

**路径二：配置文件（.mcp.json）**

在项目根目录创建 `.mcp.json`，启动时自动加载：

```json
{
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data.db"]
    },
    "内部资产库": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer xxx" }
    }
  }
}
```

#### 2）使用流程

配置完成后不需要额外操作，工具自动生效：对话中直接提需求，Agent 自动调用对应 MCP 工具，例如：

* "用 sqlite 查一下 orders 表的结构"

* "从资产库里检索 CC桌面端 最近的 5 个原型"

* **首次调用需授权**：弹出权限确认，勾选"总是允许"后存入设置，后续免确认

* **验证状态**：随时问我"MCP 服务器状态"检查连接；工具调用记录可审计

要点：

* 工具名格式：`mcp__服务器名__工具名`（如 mcp**sqlite**query）
* 密钥只写在 env/headers 里，不要写进对话

![MCP 工具调用](/screenshots/desktop-mcp-tool.webp)

### 5.2 插件

插件市场是插件的发布与分发渠道（一个含 marketplace.json 清单的 git 仓库）。

**官方插件市场（wave-plugins-official）** 随产品内置启用，与其他市场一样在打开插件市场界面时自动刷新市场清单，提供以下插件：

| 插件            | 用途                                                                     |
| --------------- | ------------------------------------------------------------------------ |
| document-skills | 文档处理套件：docx / xlsx / pptx / pdf 的读取、创建与编辑                |
| typescript-lsp  | TypeScript / JavaScript 语言服务器（补全、跳转、诊断等代码智能）         |
| chrome-devtools | Chrome DevTools MCP：浏览器自动化（导航、元素检查、截图、网络监控）      |
| code2spec       | 从代码库生成 requirements / plan / tasks 等规格文档                      |
| code2cwspec     | 从老系统（.NET、Java 等）逆向生成 CodeWave 格式规格模板（含 4 个子代理） |
| commit-skills   | Git 工作流技能集（commit / push MR / push PR / 等待合并）                |
| deep-wiki       | AI Wiki 生成器（Mermaid 图表、源码引用、llms.txt，含 3 个子代理）        |
| tavily-search   | Tavily 搜索引擎 MCP，为 Agent 提供实时网络搜索能力                       |
| frontend-design | 生产级前端界面设计技能                                                   |

#### 1）安装插件

插件市场从首页左侧边栏「新对话」下方的「插件市场」进入整页视图（页面自带返回，会话侧边栏保留），在对话中输入 `/plugin` 也进入同一个整页——桌面端只有这一个入口，设置页的左侧导航里不再摆「插件市场」项（VSCE / JetBrains 没有侧边栏整页，那两个宿主的设置页仍保留该入口）。市场 Tab 直接显示各市场自身的名称（内置官方市场即 `wave-plugins-official`，顺序即注册顺序）；按 Tab 浏览插件，可用「全部 / 已安装 / 未安装」筛选或按关键词搜索，点击行内「安装」后选择安装作用域（用户 / 项目 / 本地），一键安装；安装后即可在对话中使用。

市场多到一行放不下时，切换行自身横向滚动（滚动条不占位、不影响右侧入口），并且还有未展示市场的那一端会出现一层渐隐——右侧还有市场时右端渐隐，滚到最右端即消失，往左滚过之后左端同理出现。渐隐只是提示层：不改变 tab 与右侧按钮的位置，也不拦截点击。

添加市场成功后视图会自动切到新市场，而它通常排在切换行最右端：只要它落在可视区之外，切换条就自动横向滚动把它露出来（其它切换项与右侧按钮的位置不会因此移动），不会出现「选中项不见了」。

![市场切换条溢出时两端的渐隐提示](/screenshots/spec-plugin-market-tabs-fade.webp)

![添加市场后自动滚到刚被选中的新市场](/screenshots/spec-plugin-market-tab-autoscroll.webp)

安装后插件从市场克隆到缓存目录（`~/.wave/plugins/cache/`）。

![侧边栏入口打开的插件市场整页](/screenshots/desktop-plugin-market.webp)

![插件市场整页：切换市场、筛选与已安装状态](/screenshots/desktop-plugin-market-sidebar.webp)

![选择安装作用域](/screenshots/desktop-plugin-scope.webp)

#### 2）启用 / 禁用

装好后在 settings.json 的 enabledPlugins 中管理（值为 true 启用，删掉即禁用）：

```json
{
  "enabledPlugins": {
    "document-skills@wave-plugins-official": true,
    "frontend-design@wave-plugins-official": true
  }
}
```

已安装插件在插件市场的「已安装」筛选中可见，行内展示当前安装作用域（点击「用户 ▾」可更换作用域或卸载）。把鼠标悬停（或键盘聚焦）在该作用域上时，下方会浮出提示气泡，内容只看**当前工程**（桌面端即当前选中的那条对话所属的工程）：以项目 / 本地作用域安装的插件显示一行为「工程名（工程根目录）」（例：`code-wave（/Users/me/code-wave）`，工程重名时靠路径区分）；只以用户作用域安装、不属于任何工程的插件显示「用户级安装（所有项目可用）」；宿主还没有拿到任何工程目录时显示「所属工程未知」（此时项目 / 本地两档也不可选）。同一行的版本升级胶囊与行尾「更新」按钮走的是**同一套气泡**（文案分别为「已安装 v旧，最新版本 v新」「更新到最新版本 v新」），都用自定义浮层而不是系统原生提示——同一视图里只有一种提示风格；「安装」按钮不带气泡（按钮文字已把动作说清，气泡只会重复一遍）。插件市场按市场 Tab 分块浏览，切换市场时筛选自动回到「全部」（不继承上一个市场选的分组，避免切过去只看半个列表），搜索框里已输入的关键词保持不变。

![已安装插件](/screenshots/desktop-plugin-installed.webp)

#### 3）更新插件

插件市场清单在打开插件市场界面时自动刷新（**所有市场，不区分来源，也没有开关**）——桌面端从侧边栏「插件市场」进入整页、VSCE / JetBrains 进入设置页的插件市场视图时即触发，刷新期间工具栏显示「检查更新中…」；刷新只拉取市场检出内容（远程仓库 `git pull` / 官方市场镜像 zip 快照），**不会**自动升级已安装的插件，宿主启动与对话初始化都不刷新。存量配置里的 `marketplaces.<name>.autoUpdate` 不再影响任何行为。

插件升级有两个显式入口：插件行内出现新版本时的「更新」（单个插件），或筛选行里的「更新」（在「全部 / 已安装 / 未安装」分段器的右侧，带数量）一次批量升级**当前市场**的插件——数量就是当前市场里已安装且有新版本的插件数，切换市场时它跟着变，当前市场没有可更新插件时这个按钮不出现；两者都按进入视图时刷新好的清单执行、自身不再拉取检出。版本状态显示在插件名右侧：未安装只显示可安装的版本号胶囊（如 `v2.3.1`），已安装且已是最新只显示当前版本号，已安装且落后则是一个与前者同一形制的版本胶囊、内容为「`v当前 → v最新`」——左段读作「当前已安装」、右段读作「最新版本」，方向由中间的箭头承载；胶囊右侧再跟一个橙色「可更新」徽标（可更新的橙色语义只落在这个徽标上）；行内随之出现「更新」按钮（已安装且已是最新的行没有状态按钮——已安装这件事由作用域下拉本身表达）。

因为这一次点击会批量改动插件，它会先弹出确认对话框：正文注明作用范围是「**<当前市场名> 市场**下」并汇总「共 N 个插件可更新」，再逐行列出该市场中可更新插件的名称、版本变化（`v旧 → v新`）与安装作用域；待更新插件较多时清单区自身滚动、弹窗不会撑高。点「更新」才真正下发更新（只作用于这个市场），点「取消」或按 `Esc` 只关弹窗、不发任何请求。插件行内的单插件「更新」不弹这个确认框。

![当前市场更新的确认弹窗](/screenshots/spec-plugin-update-confirm.webp)

添加 / 移除市场与行内单插件「更新」成功后，桌面端以应用级 toast（顶部居中）给出「已添加市场「<市场名>」」「已移除市场「<市场名>」」「已更新「<插件名>」至 v<版本>」——市场名取自市场自身的清单；失败原因走同一个提示渠道。批量更新的提示形如「「<市场名>」已更新 N 个插件 / 「<市场名>」已是最新」。该提示的层级高于弹窗遮罩，所以弹窗打开期间这类应用级提示不会被遮罩压暗（层级抬高的理由就是这一条，与弹窗内容无关）。

#### 4）添加新市场

市场来源的增删走插件市场视图的市场 Tab 行右侧两个图标入口：「添加插件市场」（加号）直接打开「添加插件市场」对话框，「管理插件市场」（齿轮）打开弹窗——按钮本身不带文字，鼠标悬停（或键盘聚焦）时在按钮下方显示同名提示气泡；弹窗内列出全部已注册市场（官方市场行标「官方」、不可移除），自定义市场可逐个移除（二次确认；确认框在该市场下有已安装插件时提示「该市场下的 N 个已安装插件将一并移除」，一个已安装插件都没有时不出这行提示），底部「添加插件市场」与加号入口等价——两处入口与弹窗标题同名，用户不用做名称映射。市场加得多了（列表超出弹窗可视高度）也只滚市场列表这一块：弹窗标题行与底部「添加插件市场」固定不动，不会跟着滚出视野。添加插件市场支持两种来源：**本地路径**（点击「选择文件夹」选取本地插件目录）与**远程仓库**（填 GitHub `owner/repo` 或完整 Git 地址）。市场名称由市场自身的 `marketplace.json` 清单决定，无需手填；同一来源已添加过、或其清单名称与已有市场同名时不允许添加，并提示原因；添加成功后自动切换到新市场的 Tab。

![管理插件市场：市场多到超出弹窗高度时只滚列表，标题与底部入口固定](/screenshots/spec-plugin-manage-markets-scroll.webp)

也可以在 settings.json 注册（支持 GitHub / Git URL / 本地目录三种源）：

```json
{
  "marketplaces": {
    "团队市场": {
      "source": { "source": "github", "repo": "netease-lcap/team-plugins" }
    }
  }
}
```

作用范围：用户级 `~/.wave/settings.json`（全部项目）、项目级 `.wave/settings.json`（当前项目）、本地级 `.wave/settings.local.json`（个人覆盖，不提交 git）。

#### 5）创建团队自有市场

* 建一个 git 仓库，根目录放 `.wave-plugin/marketplace.json`（清单：插件名、描述、source 路径/远程 git URL）
* 每个插件目录内有自己的 `.wave-plugin/plugin.json` 清单
* 插件可打包技能（skills/）、命令（commands/）、钩子、MCP/LSP 服务器、工作流脚本（workflows/，按 `<插件名>:<脚本名>` 调用）
* 在 settings 注册该市场，团队全员即可通过 `/plugin` 打开插件市场搜索安装

## 6. 设置

设置页是 CodeWave IDE 桌面端的配置管理中心，从侧边栏底部账户卡片的菜单中的「设置」打开（覆盖会话区的全页面，侧边栏保持可见）。左侧导航按三组共 7 项组织：「通用」（全局设置 / 个性化）、「工作区」（项目设置）、「AI 与扩展」（技能 / 子代理 / 钩子 / MCP 服务），当前激活项有高亮态——插件市场不在这里，它由侧边栏「新对话」下方的入口打开整页（见 [5.2 插件](#_5-2-插件)）。点左上角返回即回到原对话，未发送的输入内容与正在生成的回复都原样保留。

### 6.1 账户卡片与设置入口

侧边栏底部账户卡片默认只展示个人信息一行（登录状态：头像、姓名）。已登录时点击个人信息行热区弹出纯功能菜单（「设置 / 企业控制台 / 帮助文档 / 退出登录」四项）；未登录时显示整条「登录」按钮与「更多」按钮（菜单含登录项）。「设置」打开设置页面。

用量信息收在浮层里：点个人信息行尾部的**用量按钮**，在卡片上方弹出与卡片等宽的浮层（不改变卡片高度、不推挤侧边栏其余部分），再点按钮、点浮层外或按 Esc 收起。用量出预警（余额不足 / 额度耗尽 / 套餐到期 / 被阻断）时按钮右上角带一颗小圆点，收起态也不会漏看。

浮层内的用量是**互斥的两个维度**，由「套餐用量 / API 余额」两个文字页签切换，默认停在套餐维度：

* **套餐用量维度**：本自然周（上）与本滚动月（下）两根余量进度条，右上角显示套餐到期日
* **API 余额维度**：已用 / 剩余两行金额；右上角的 ⓘ 说明余额会在套餐额度耗尽时才被使用
* 某个维度不可用（如管理员未设置限额）时，直接展示有数据的那一维，不渲染页签

![账户卡片](/screenshots/desktop-account-card.webp)

### 6.2 全局设置

「全局设置」视图拆两个区块：「基础设置」卡片与「桌面端设置」区块（后者仅桌面端显示）。

「基础设置」卡片展示走共享配置的 AI 回复语言与上下文长度（K 值）：

* **AI 回复语言**：下拉选择，中文（zh-CN）/ English（en-US），仅影响 AI 回复用语，不改变界面语言
* **上下文长度**：数字输入，16–1000 K，下方标注「全局默认；当前模型自带上下文上限时以模型配置为准」

这两个（以及「个性化」里的自动记忆开关与轮次）都是**用户偏好**，落点是当前会话所在进程的用户级 `~/.wave/settings.json`（远端 / SSH 会话即远端机器上的该文件）：点「保存」先落盘、再实时重载到已有会话，从下一轮对话起生效——不重启对话，也不打断正在进行的工作。保存成功 / 失败经全局 toast 提示。

**未设置态**：文件里没有某个键时，页面显示系统默认值，而不是编造一个值写回去——语言下拉出现并选中「未设置（默认：中文）」、数字输入留空并显示灰字占位符（「跟随模型配置（默认 200K）」/「默认 1 轮」）。保存只把**真正改动过**的字段写盘（未设置或未改动的键一律省略），因此「进设置页一个字不改地点保存」不会把机器环境里已有的配置钉死。页面不提供「清除 / 恢复默认」按钮，要让某个键退回未设置态需手动改文件。

**生效值与来源**：页面展示的是**生效值**，不是文件里的值——用户文件只是取值链中的一层，企业下发的组织配置与机器环境变量都能盖过它：

* 来源为**组织配置**（Remote 下发）：显示生效值并置灰，行内提示「由组织配置管理」（组织策略不可被本地设置覆盖）
* 来源为**系统环境变量**：同样显示生效值，行内提示「当前值来自系统环境变量；保存后以本页设置为准」，但**保持可编辑**（用户文件优先级高于环境变量，在此保存即覆盖）
* 来源为用户文件 / 默认值：与普通行一致，无来源说明

「桌面端设置」区块（2026-09-08 拍板从「基础设置」拆出）展示桌面端独有的本地偏好——经 host 直连通道持久化，不写入共享 settings.json，选择即时生效、无需「保存」：

* **主题**：跟随系统（默认）/ 浅色 / 深色，选择即时生效并持久化，重启后保持且首帧无闪烁
* **接收 Beta 版更新**：开关（默认关闭 = stable），开启后自动更新将接收测试版通道（Beta）分发的版本；未登录（无企业版服务地址）时开关置灰不可切换

![全局设置](/screenshots/desktop-settings-global.webp)

未设置态（语言未设置、上下文长度留空显示占位符）：

![设置页未设置态](/screenshots/desktop-settings-unset.webp)

生效值与来源（语言由组织配置管理、上下文长度来自系统环境变量）：

![生效值与来源](/screenshots/desktop-settings-source.webp)

### 6.3 个性化

通过文本内容定义 AI 的长期工作规则与记忆行为：

* **AGENTS.md**：用户级 / 项目级两个 Tab 展示对应规则文件内容，可直接编辑并分别通过「保存用户级配置」/「保存项目级配置」写盘
* **自动记忆规则**：「开启自动记忆」开关（默认开启）与「触发记忆提取会话轮次」输入（1–100 轮，默认 1 轮），点「保存」后与「全局设置」同样落盘并实时生效。轮次未设置时留空并显示「默认 1 轮」占位符；来源为组织配置 / 系统环境变量时同样标注来源（开关一行不做占位态——它的真实默认就是「开」）

![个性化设置](/screenshots/desktop-settings-personalization.webp)

### 6.4 项目设置

内置插件 SDD（规格驱动开发）开关——该视图的唯一交互控件：切换写回项目 `.wave/settings.json` 的 `enabledPlugins`（自动创建或更新功能规格说明）。插件变更（安装 / 卸载 / 启用 / 禁用 / 更新，含本开关）**不再需要重建对话**：变更落盘后桌面端弹一个确认框「插件已变更，重新加载后生效」，点「立即重新加载」就在同一对话内就地生效（不打断正在生成的回复）；点「稍后」关掉即可，之后在对话框里输入 `/reload-plugins` 也能补上——未重新加载前，既有对话继续用旧配置，新建对话自动按新配置装载。详见 [4.1 SDD](#_4-1-sdd)。

![项目设置](/screenshots/desktop-settings-project.webp)

![插件变更待应用提示](/screenshots/desktop-settings-plugin-change.webp)

### 6.5 技能、子代理、钩子与 MCP 服务

「AI 与扩展」组下的四个视图，按来源分组浏览当前生效的配置（插件市场不在此列，它由侧边栏入口打开整页，见 [5.2 插件](#_5-2-插件)）：

* **技能**：按来源 Tab 分组（内置 / 用户 / 项目 / 插件），展示技能名称、描述与 `/技能名` 调用方式
* **子代理**：按来源分组展示子代理定义（名称、模型、描述）
* **钩子**：按事件分组展示已配置命令（用户级 / 项目级双 Tab）
* **MCP 服务**：服务器列表（类型 / 端点 / 连接状态 / 工具数），可连接 / 断开

![技能设置](/screenshots/desktop-settings-skills.webp)

![子代理设置](/screenshots/desktop-settings-subagents.webp)

![钩子设置](/screenshots/desktop-settings-hooks.webp)

![MCP 设置](/screenshots/desktop-settings-mcp.webp)

### 6.6 更新

新版本在后台自动下载，下载过程中侧边栏不显示任何更新提示。下载完成后，侧边栏账户卡片个人信息行右侧出现「更新」按钮；点开是「重启以完成更新」确认框，里面列出本次更新包含哪些改动，看完点「立即重启」即完成升级——应用不会自动重启打断工作，也不会自己弹窗。下载失败不影响使用，下一次检查会自动重试。