---
url: /wave-agent/specs/desktop/desktop-settings.md
description: >-
  CodeWave IDE 桌面端设置页面：覆盖整个窗口的导航与视图、可编辑的全局设置与个性化、结果型反馈统一走宿主 toast、用户偏好写入用户级
  settings.json 实时重载且不重建会话
---

# 功能规格说明：桌面端设置页

> 本规格描述设置页本身：导航结构、各视图的可编辑项、保存路径与生效时机。设置页里的账户相关界面见 [desktop-account.md](./desktop-account.md)。

## 用户场景与测试

### 用户故事：设置页面（优先级：P1）

作为用户，我希望通过侧边栏账户卡片菜单（已登录为点击个人信息行热区弹出的纯功能菜单，未登录为「更多」按钮菜单；两态菜单均含「设置」项）中的「设置」打开完整的设置页面，在左侧导航分组中浏览当前生效的全部配置与状态（语言、主题（桌面端）、上下文长度、AGENTS.md、自动记忆、项目插件、技能、子代理、钩子、MCP 服务；桌面端导航里**没有**「插件市场」——它由侧边栏「新对话」下方的入口打开整页，VSCE / JetBrains 仍以设置页导航项承载，见 [plugin.md](../ecosystem/plugin.md)「插件市场」场景 3 与 A-016），并可直接修改「全局设置」与「个性化」中的基础配置项，以便了解并调整当前环境的配置全貌。

**为什么是这个优先级**：设置页是桌面端的管理中心，用户拍板按原型做成全页面（覆盖会话区，2026-08-31 曾拍板全部导航项只读展示；2026-09-01 原型走查用户恢复部分可编辑：全局设置（AI 回复语言/上下文长度）与个性化（自动记忆开关/轮次）提供编辑控件与保存按钮（对齐旧配置弹窗交互），保存经 stdio `updateConfiguration` RPC 写回配置并即时生效（**2026-09-10 变更**：用户偏好改走写用户级 `~/.wave/settings.json` + SDK 实时重载，不再经 `AgentOptions` 覆盖层下发，保存不再重建会话，详见下文「用户偏好的保存路径与重建时机」），其余视图（AGENTS.md 文本区、技能/子代理/钩子/MCP）保持只读浏览或原有管理形态；2026-09-04 用户拍板「个性化」AGENTS.md 文本区一并恢复可编辑（用户级/项目级各提供独立保存按钮，写回对应 AGENTS.md 文件，与 2026-08 批次 2 的读写 RPC 同源），此后仅技能/子代理/钩子/MCP 视图保持只读浏览或原有管理形态；2026-09-08 用户按设计师高保真走查拍板：设置页进一步占满整个 view——连会话侧边栏一并覆盖（不再「侧边栏保持可见」），macOS 隐藏标题栏下系统红绿灯由设置页自身左导航顶部承接；VSCE/JetBrains 无侧边栏账户区，同样以编辑器区域标签页 webview 承载（对齐 plan 标签页的呈现机制，从现有配置入口/命令打开），内容与 desktop 一致。**「远程控制」项（2026-10-17 由独立弹层搬入本页）**：它是「通用」组的**第三项**（全局设置 / 个性化 / 远程控制），由 desktop / VSCE / JetBrains 三端渲染——与「MCP 服务」同一层级（都是**这台机器**上的一项能力，不属于某个项目），内容只有状态、页面地址与二维码、开启/断开；入口仍是聊天输入框里的 `/remote-control`，只是改为打开本页并选中该项（语义见 [remote-control.md](../remote/remote-control.md)「`/remote-control` 打开设置页的远程控制选项卡」）。2026-09-02 走查追加「主题」选择（仅桌面端展示，三态与行为见「主题设置」故事）：主题为桌面端本地显示偏好（不写入共享配置），选择即生效并持久化。2026-09-08 拍板：「主题」与「接收 Beta 版更新」从「基础设置」卡片拆出，独立成「桌面端设置」区块，仍位于「全局设置」视图内（非独立导航项）——两者是桌面端独有的本地设置通道（host 直连 `setThemeSource`/`setUpdateChannel` 持久化于 configStore，不走 stdio `updateConfiguration`、不写入共享 settings.json），与「基础设置」中走 stdio 的语言/上下文长度区分展示；仅桌面端渲染该区块。2026-09-10 用户拍板（保存路径根因治理）：设置页「全局设置」/「个性化」的用户偏好**不再**经 stdio `updateConfiguration` 当 `AgentOptions` 覆盖层下发（该覆盖层优先级高于 settings.json，会永久遮蔽实时配置——这正是此前「保存必须重建全部会话」的根因），改为写用户级 `~/.wave/settings.json` 并由 SDK 实时重载（`LiveConfigManager`）在各会话下一轮开始时生效，保存因此**立即回执、界面即时刷新、不重建任何会话**；插件装卸等变更也**不再走重建**（2026-09-18 拍板改为就地重载——变更落盘只出现一次提示，由用户敲 `/reload-plugins` 触发换装，见 [plugin.md](../ecosystem/plugin.md)「插件变更的就地重载」），本端**不弹任何重建确认框**。

**独立测试**：desktop 经账户卡片菜单（已登录热区纯功能菜单/未登录「更多」按钮菜单）点「设置」验证全页面导航（8 项 3 组，全部可进入；桌面端导航里没有「插件市场」项）与会话侧边栏被覆盖（单会话与分屏两形态均覆盖、返回恢复原布局）；全局设置/个性化修改语言、上下文长度、自动记忆开关与轮次并保存，验证新值生效（配置回发刷新展示）、保存**不重建任何 live 会话**（会话不销毁、排队消息不清空、流式不打断）；未修改任何值直接保存验证同样不重建；插件变更场景验证**不弹任何重建确认框、不重建任何会话**，只弹一次「插件已变更，重新加载后生效」确认框（点「立即重新加载」或敲 `/reload-plugins` 后在同一会话内生效）；VSCE/JetBrains 从命令面板/设置入口打开编辑器区域标签页 webview，验证内容与 desktop 一致；钩子视图按事件分组展示已配置命令（用户级/项目级双 tab）；MCP 视图展示服务器列表（类型/端点/连接状态/工具数）并可连接/断开；项目设置视图展示 SDD 开关状态并可切换。

**验收场景**：

1. **假设**desktop 侧边栏账户卡片已展示，**当**用户经账户卡片菜单（已登录为点击个人信息行热区、未登录为「更多」按钮菜单）点击「设置」，**则**设置页占满整个 view——会话侧边栏一并被覆盖（不再保留），页面仅显示设置页自身：左侧导航与右侧内容区，导航顶到窗口最左、内容顶到窗口最上；macOS 隐藏标题栏下系统红绿灯浮于设置页左导航顶部左上角（见 desktop-shell「macOS 隐藏标题栏」设置页场景）；再次点击设置页左上角「返回应用」（现文案「返回」）或关闭方式可回到会话视图（会话侧边栏随之恢复）。
2. **假设**设置页面已打开，**当**用户查看左侧导航，**则**必须分为三组共 8 项：「通用」（全局设置/个性化/**远程控制**）、「工作区」（项目设置）、「AI 与扩展」（技能/子代理/钩子/MCP 服务），当前激活项有高亮态；桌面端**不出现「插件市场」项**（它由侧边栏「新对话」下方的入口打开整页，见 [plugin.md](../ecosystem/plugin.md)「插件市场」场景 3 与 A-016），VSCE / JetBrains 没有侧边栏整页、设置页这项是它们唯一入口；浏览类视图不出现编辑控件，「全局设置」「个性化」仅对可编辑项展示控件。
3. **假设**用户点击「全局设置」，**当**进入该视图，**则**必须显示两个区块：「基础设置」卡片与「桌面端设置」区块（后者仅桌面端渲染）。「基础设置」卡片展示当前生效的 AI 回复语言（中文 zh-CN / English en-US）与上下文长度（K 值）——**补全相关的两行（「代码补全」开关 / 「补全模型」下拉）不在本端展示**：桌面端没有代码编辑器、不提供行内补全，这两行只由提供补全的插件端（VS Code / JetBrains）设置页渲染，语义见 [code-completion.md](../editor/code-completion.md) 边界情况「补全设置行的宿主范围」；语言为下拉选择（中文/English）、上下文长度为数字输入（16–1000 K，读写同一个全局键 `env.WAVE_CONTEXT_WINDOW`，行内须给出一句可见说明如「全局默认；当前模型自带上下文上限时以模型配置为准」——**2026-09-10 拍板**，语义见 [agent-config.md](../core/agent-config.md) 边界说明「上下文长度的落点」），**改动即时写盘——没有「保存」按钮**（2026-11-04 拍板，见 [agent-config.md](../core/agent-config.md)「设置页控件的保存时机」）；**文件里没有该键时不得假装一个有值**：语言下拉首项为「未设置（默认：中文）」并选中、上下文长度输入框留空并以灰字占位符「跟随模型配置（默认 200K）」显示系统默认（完整规则见 [agent-config.md](../core/agent-config.md)「插件端配置入口」故事场景 7–8）；被更高层覆盖的键必须**如实显示生效值**，不得回退显示用户文件里的值、也不得显示「未设置」态（见 [agent-config.md](../core/agent-config.md)「插件端配置入口」故事场景 9 与边界说明「用户偏好的层与来源」）：企业下发的 Remote 组织配置（用户本地无法覆盖）→ 置灰 + 行内提示「由组织配置管理」；机器环境变量给值 → 显示生效值 + 一句来源说明但**仍可编辑**（保存即写进用户级文件并覆盖环境变量的值）；保存把用户偏好写入用户级 `~/.wave/settings.json`（经 SDK 实时重载在各会话**下一轮开始时**生效，见 [agent-config.md](../core/agent-config.md)「设置实时重载」）且**只把改动过的字段**放进载荷（省略键 = 不改该键），保存回执**不等待任何会话重建**——不销毁/重建 live 会话、不清空排队消息、不打断流式输出，界面即时刷新为新值；写盘成功**不弹任何提示**（控件的新状态就是回执），失败才经宿主提示并回滚界面（模板与可操作入口见本故事「设置页反馈语义」），设置页自身不渲染页面内自建提示文字。「桌面端设置」区块位于「基础设置」下方（2026-09-08 拍板：原属「基础设置」卡片的「主题」「接收 Beta 版更新」两行拆出独立成区），展示桌面端独有的两条本地偏好：「主题」选择（跟随系统/浅色/深色，默认跟随系统）与「接收 Beta 版更新」开关——两者均选择即时生效并持久化、不依赖「保存」按钮；持久化经 host 直连通道（`setThemeSource`/`setUpdateChannel`）写入桌面 configStore，不走 stdio `updateConfiguration`、不写入共享 settings.json（语义见 desktop-distribution「主题设置」「接收 Beta 版更新」故事），VSCE/JetBrains 设置页不显示该区块。
4. **假设**用户点击「个性化」，**当**进入该视图，**则**必须显示两块内容：「AGENTS.md」（用户级/项目级两个 tab，文本区可编辑对应文件内容，各作用域提供独立「保存」按钮（文案含当前作用域，如「保存用户级配置」）；保存经 `setAgentsContent` RPC 写回对应文件——用户级 `~/.wave/AGENTS.md`、项目级当前项目 AGENTS.md，保存结果经宿主全局 toast 提示（成功「保存成功」/失败「保存失败：<原因>」，语义见「设置页反馈语义」））与「自动记忆规则」（开启自动记忆为开关、**拨动即写**；触发记忆提取会话轮次为数字输入（1–100 轮）、**失焦或回车时写**——两者都没有「保存」按钮；**文件无该键时**：轮次输入框留空并以灰字占位符「默认 1 轮」显示系统默认（见 [agent-config.md](../core/agent-config.md)「插件端配置入口」故事场景 7），开关**不做占位态**（其真实默认即「开」，三态开关更难用）继续显示为开；被更高层覆盖时同样**如实显示生效值**：Remote 组织配置 → 置灰 + 「由组织配置管理」，机器环境变量 → 显示生效值 + 来源说明但**仍可编辑**（见 [agent-config.md](../core/agent-config.md)「插件端配置入口」故事场景 9）；保存只写改动过的字段（省略键 = 不改该键）；保存即生效且影响运行中的会话——关闭后从下一轮起不再触发记忆提取（不写入自动记忆文件）、新建会话同样不提取，重新开启后恢复且计数从开启时刻重新累计，频率按新值生效（语义见 memory-management「自动记忆开关」）；保存同样写入用户级 `~/.wave/settings.json`、**不重建会话**（含自动记忆安全区目录随开关热更新，见 [agent-config.md](../core/agent-config.md)「设置实时重载」）；写盘成功不弹提示、失败才提示并回滚界面（语义见「设置页反馈语义」））。项目级 AGENTS.md 仅针对当前项目，无项目切换按钮。
5. **假设**「个性化」AGENTS.md 文本区可编辑且两个作用域内容均已加载，**当**用户在用户级编辑草稿后切换到项目级再切回用户级、或点击「保存用户级配置」，**则**切换 tab 不触发任何保存/写入，各作用域草稿相互独立保留（切换只改变文本区绑定，未保存的修改不丢失）；仅点击当前作用域的保存按钮时经 `setAgentsContent` 写回该作用域对应文件，host 回发 `agentsContentSaved` 后经宿主全局 toast 提示保存结果（成功「保存成功」/失败「保存失败：<原因>」，语义见「设置页反馈语义」）；设置页不再渲染页面内自建提示文字，提示生命周期由宿主 toast 通道既有规则管理（无「切换导航项即清除」的页面内状态）。
6. **假设**用户点击「钩子」，**当**进入该视图，**则**必须只读展示钩子配置，提供「用户级/项目级」双 tab 切换（对齐个性化视图）：按事件分组（如 PreToolUse、PostToolUse、UserPromptSubmit、SessionStart 等）展示每个事件下已配置的命令及可选参数（异步、超时、匹配器），未配置任何钩子的事件组不显示或显示空态说明；用户级/项目级条目提供新建/编辑/删除（行为与 hooks-command / hooks.md 管理故事一致：编辑预填提示词并打开 settings.json、删除二次确认后直接删配置），插件级条目只读；删除成功经宿主全局 toast 提示「已删除钩子「`<hookName>`」」（失败提示沿用该故事错误提示语义）。
7. **假设**用户点击「MCP 服务」，**当**进入该视图，**则**必须展示 MCP 服务器列表（名称、类型（stdio/sse/http）、命令或端点 URL、连接状态（已连接/连接中/断开/错误）、可用工具数），提供「用户级/项目级」双 tab 切换：用户级 tab 读取 `~/.wave/mcp.json`、项目级 tab 读取项目根 `.mcp.json`；每个服务器提供「连接/断开」操作（对齐现有 MCP 连接管理能力）；用户级/项目级服务器提供新增/编辑/删除（与 mcp.md 管理故事一致：编辑预填提示词并打开配置文件、删除二次确认后直接删配置），插件级服务器只读；删除成功经宿主全局 toast 提示「已移除 MCP 服务器「`<serverName>`」」（失败提示沿用既有「移除 MCP 服务器失败」错误语义）。
8. **假设**用户点击「项目设置」，**当**进入该视图，**则**必须展示内置插件 SDD 开关状态（读取项目 `.wave/settings.json` 合并后的 `enabledPlugins`）；开关为唯一交互控件——切换开关写回配置文件并生效（**不重建会话、不弹重建确认框**：变更落盘后弹一次「插件已变更，重新加载后生效」确认框，用户点「立即重新加载」（或敲 `/reload-plugins`）后在同一会话内使插件技能与引导生效，见 [plugin.md](../ecosystem/plugin.md)「插件变更的就地重载」），其余内容只读。开关状态**每次进入该视图都以当前会话/活动项目的工作目录重新读取**，不得沿用上次进入缓存的旧值：会话/工作目录切换后重入视图必须刷新为该工作目录的真实配置；外部变更（手动编辑 `.wave/settings.json` 或其他端切换该开关）后重入视图同样必须刷新一致——避免出现「配置文件已启用（`sdd@builtin: true`）而开关仍显示关闭」的状态矛盾。
9. **假设**用户点击「技能」或「子代理」，**当**进入该视图，**则**按来源 Tab 展示列表（项目来源 Tab 平铺，无项目分组卡片），提供详情查看、新建、编辑、删除等管理操作，与 agents-command / skills-command 规格一致；删除成功经宿主全局 toast 提示「已删除技能「`<name>`」」/「已删除子代理「`<name>`」」（失败提示沿用各删除故事错误提示语义）。
10. **假设**VSCE/JetBrains 宿主环境，**当**用户通过命令面板（如「打开设置」）或现有设置入口打开设置，**则**必须在编辑器区域打开设置标签页 webview（对齐 plan 标签页：VSCE 为编辑器区域面板、JetBrains 为编辑器标签页），内容与 desktop 设置页一致（同一导航结构与视图）；再次调用打开时复用已打开的标签页而非新建。
11. **假设**设置页任一视图打开，**当**用户修改了全局设置/个性化的任一个可编辑项，**则**在控件自身的提交时机（开关与下拉=选中当场；数字=失焦或回车）立即把**那一个键**写入用户级 `~/.wave/settings.json`（经 SDK 实时重载生效，**不重建会话**）——设置页没有「保存」按钮，也不存在「未保存」状态（见 [agent-config.md](../core/agent-config.md)「设置页控件的保存时机」）；**没有改动时不发任何报文**，打开设置页、切换导航项、切换视图 tab、关闭设置页本身不得触发任何写入或会话重建。
12. **假设**desktop 处于分屏（多个 pane）或单会话布局且已打开设置页，**当**查看设置页布局，**则**设置页必须覆盖**整个窗口**——会话侧边栏与所有 pane 一并被隐藏，仅设置页可见；分屏的 pane 数量/尺寸/会话不因打开设置而销毁（会话在后台继续运行，含流式输出）；点击「返回」关闭设置页后恢复打开前的布局（分屏 pane 布局、侧边栏展开/收起、聚焦会话、消息滚动位置原样保留），不新建会话、不打断流式。
13. **假设**用户没有改动任何控件（含控件仍处于「未设置」态的情形），或把某个控件拨回/改回与原生效值相同，**当**停留在设置页、来回切换导航项，**则**一条写盘报文都不发、不落盘、不弹任何提示——未改动的键一律不出现在载荷里（省略键 = 不改该键，未设置态不写该键，见 [agent-config.md](../core/agent-config.md) 边界说明），也**不得重建任何会话**、不得清空排队消息、不得打断流式输出。
14. **假设**本次保存只涉及热生效键（AI 回复语言、上下文长度、自动记忆开关/轮次等），**当**保存完成，**则**不得重建任何会话；**假设**本次变更包含插件安装/卸载/启停/更新或内置插件开关，**当**变更落盘，**则**同样不得重建任何会话、不得弹任何重建确认框——变更只产生一个「待应用」信号并由宿主提示一次（逐字文案见 [plugin.md](../ecosystem/plugin.md)「插件变更提示」），由用户敲 `/reload-plugins` 触发就地换装。
15. **假设**用户敲 `/reload-plugins`，**当**重载执行，**则**在同一会话内就地换装、会话 id 不变、消息与转录连续、不打断正在生成的回合；**假设**用户未敲命令，**则**不存在任何自动重建路径，也不登记「待重建」待办——变更只对新建对话自动生效（完整语义见 [plugin.md](../ecosystem/plugin.md)「插件变更的就地重载」）。
16. **假设**分屏的会话在生成过程中用 bash 工具 `cd` 进了项目下的子目录（agent 的当前工作目录随之被改写），**当**用户打开或操作任一项目级配置视图——「MCP 服务」项目级 tab、「项目设置」、「钩子」项目级 tab、「个性化」的项目级 AGENTS.md——**则**其读取与写入必须一律以**会话稳定根**（该会话启动时的工作目录，worktree 会话即其 worktree 路径）作为「项目根」：落点始终是该会话所属项目的 `.mcp.json`、`.wave/settings.json`、hooks 配置与 `AGENTS.md`，不得落到会话过程中 `cd` 进去的嵌套子目录上；**假设**同一分屏的会话尚未绑定（新会话态），**则**回落到该分屏当前的工作目录。这与「用户正在看的目录」（文件面板 / 差异 / 终端，跟随被改写后的当前工作目录）是两个不同的概念，不得混用。

***

### 设置页反馈语义（2026-09-09 设计师走查拍板：设置页不得自建一套提示）

* **统一走宿主全局 toast**：设置页的「结果型」反馈——AGENTS.md 保存、四视图删除类操作的**成功**，以及**任何写盘失败**（含用户偏好键的即时写盘）——均经**宿主全局 toast 通道**提示（desktop 为 host `showToast` → webview 应用级 ToastStack（顶部居中新形态，见下「toast 形态与路由」）；VSCE 为 `vscode.window.showInformationMessage`/`showErrorMessage` 原生通知；JetBrains 为 IDE 通知气球（Info 变体，失败沿用既有 `IdeService.showError`））；设置页自身**不渲染任何页面内自建提示文字**（如卡片内/文本区旁的灰色小字成功/失败消息），不再保留「切换导航项即清除」的页面内瞬态反馈状态。
* **成功/失败文案模板（2026-11-04 补充）**：**用户偏好键写盘成功不提示**（开关/下拉/数字框改动后控件自身的新状态即回执——这正是主流做法：VS Code 写入静默、claude.ai 的开关 mutation 显式 `noToast`、macOS 系统设置全程无提示）；用户偏好键写盘失败「设置未写入「<键名>」：<原因>」——**不带任何动作按钮**（三端同语义；2026-11-04 拍板撤掉早先设计的「打开设置文件」入口）：失败原因是权限/磁盘/远端连接，打开用户级 `~/.wave/settings.json` 帮不上忙，何况即时生效下用户本就不需要手改那份文件；真正的补救是**界面已回滚到上一次生效值**，用户看到的开关状态就是磁盘上的真实状态——失败信息必须让用户知道**哪一项没写进去**，因为一次操作只写一个键、用户刚点的是哪一个未必还能记住；仍是显式动作的 AGENTS.md 保存沿用「保存成功」/「保存失败：<原因>」；删除类成功「已删除技能「<对象名>」」「已删除子代理「<对象名>」」「已删除钩子「`<hookName>`」」「已移除 MCP 服务器「<对象名>」」/失败「删除/移除技能/子代理/钩子/MCP 服务器失败：<原因>」。提示停留时长遵循各宿主通道既有规则（桌面端应用内 toast 见下「信息型 toast 停留时长」；不新增按提示类型自定义的停留逻辑）。
* **宿主在结果确定时发出**：toast 由 host 在操作结果确定后发出（desktop 删除/连接命令的 try/catch 成功分支；配置保存只在**失败**分支发提示——`handleUpdateConfiguration` 落盘并写用户级 settings.json 后**即刻回包**、成功不发提示，失败才发，且不得等会话重建完成、不得以重建完成与否决定成败；`handleSetAgentsContent` 结果处，VSCE 两路由 handler，JB MessageHandler），不以 webview 乐观时序为准。
* **写操作需 live agent**：删除/保存类写操作在宿主侧 agent 缺失（未初始化/无会话）时不得静默成功或空转——须给出失败 toast（对齐 JB `setAgentsContent`「智能体未初始化」诚实失败先例）；Webview 列表视图在无 agent 时读到的空列表不产生删除入口，但 host 仍须防御直接命令调用。
* **非本拍板范围的提示保持不变**：MCP 连接/断开成功不弹提示（列表状态即结果）、失败给出错误提示（见下「toast 形态与路由」的语义色范围）；「保存中…/连接中…/断开中…」进行态仍由按钮禁用与文案承载。
* **toast 形态与路由**（2026-09-10 设计师拍板）：桌面端应用内 toast 按宿主**显式声明的 `position`**（不以「是否带按钮」推断）分两个互不干扰的栈——**应用级全局提示**（`position` 缺省 `"top"`，含本故事的设置页结果型反馈）渲染为**顶部 toast 条**（水平锚定内容列/工作区中心、语义图标随提示等级）；**后台会话确认提示**（`position: "bottomRight"`，见 [desktop-sessions.md](./desktop-sessions.md)「后台会话确认提醒」）保持既有**右下角通知形态**（不带语义图标），**不并入**顶部新形态，两栈可同屏共存。**语义三色只用于设置页结果型提示**（AGENTS.md 保存成功/失败、用户偏好写盘失败、删除/移除技能·子代理·钩子·MCP 成功/失败、MCP 连接/断开失败；插件变更的两句一次性提示不在其列——它们按中性提示呈现，见 [plugin.md](../ecosystem/plugin.md)「插件变更提示」）：成功=成功色、失败=失败色，均配浅色底 + 同色图标/文字（不只靠色）；**其余应用级提示一律中性**——默认浮层底色、不渲染成功/失败/信息图标，不得缺省回退为任一彩色语义。
* **信息型 toast 停留时长（2026-09-22 拍板：2 秒 → 8 秒）**：无操作按钮的信息型 toast（两个栈通用）统一在 **8 秒**后自动消失；带操作按钮的 toast 不自动消失，等用户处理或手动关闭。时长是 ToastStack 的**单一全局常量**，不按提示类型 / 单条提示自定义字段，也不做悬停暂停（「不新增自建停留逻辑」仍成立——改的是通道自身的既有规则，不是给个别提示开后门）。**起因**：2026-09-22 用户反馈 2 秒根本读不完——安装 / 卸载 / 更新插件会同时出现两条无按钮提示（如 `已安装「X」（作用域：user）` + `插件已变更。运行 /reload-plugins 使其生效。`），两条同刻挂载、同刻消失，第二条还带一条要照抄的命令；叠加提示条本身无悬停暂停、到点直接卸载，用户来不及读完。**8 秒的取值来源**：对齐 Claude Code 的通知默认超时（`DEFAULT_TIMEOUT_MS = 8000`），不另立数字。**影响范围**：仅桌面端应用内 toast（VSCE / JB 的同类提示走宿主原生通知，停留时长由宿主与系统设置决定，无此常量）。

***

### 用户偏好的保存路径与重建时机（2026-09-10 拍板：保存不重建会话）

* **保存路径（用户偏好）**：设置页「全局设置」（AI 回复语言、上下文长度）与「个性化」（自动记忆开关/轮次）保存的用户偏好，一律写入**用户级 `~/.wave/settings.json`**，由 SDK 的 `LiveConfigManager` 实时重载（用户在设置页改的即文件里的值），在各会话**下一轮开始时**生效（每轮开始取一次配置快照；见 [agent-config.md](../core/agent-config.md)「设置实时重载」）。**不得**把用户偏好经 stdio `initialize` / `updateConfig` 当 `AgentOptions` 覆盖层下发（该层优先级高于 settings.json，会永久遮蔽实时配置，正是此前必须重建会话的根因）。
* **回执与刷新**：写盘的回执（`configurationResponse`）与界面刷新在**落盘后立即**给出，**不等待任何会话重建**；失败提示亦在持久化结果确定时发出（成功不发提示）。
* **不重建**：纯热生效键的写入（无论值有无变化）**不重建任何会话**——不销毁/重建 live 会话、不清空排队消息、不打断流式输出；值未变时连写盘都不发生（控件与生效值相同即不提交），更不得触发重建与队列清空。
* **不再有需要重建的构造期副作用**：**插件装卸**（安装/卸载/启用/禁用/更新插件、内置插件开关，如项目设置里的 SDD）2026-09-18 起改为**就地重载**——变更落盘后不重建会话、不弹任何确认框，由用户敲 `/reload-plugins` 在同一会话内换装（见 [plugin.md](../ecosystem/plugin.md)「插件变更的就地重载」）；自动记忆开关/频率早在 2026-09-10 改为热生效。至此**没有任何配置变更需要重建会话**（见 [agent-config.md](../core/agent-config.md)「配置变更不再需要重建会话」故事）。
* **重建确认框已废止（2026-09-18 拍板）**：插件变更 2026-09-18 起改为就地重载，本端**不再有任何重建确认框**——原先的「立即重启 / 稍后重启」两按钮、N/M 文案、`Esc` 等同「稍后重启」等条款一并取消。变更落盘后只弹一次「插件已变更，重新加载后生效」确认框（「稍后」/「立即重新加载」），由用户自己决定何时应用（见 [plugin.md](../ecosystem/plugin.md)「插件变更提示」）。
* **就地重载不打断任何会话**：敲 `/reload-plugins` 时若某会话正在生成回复、有待确认权限（等待用户确认/回答）或存在运行中后台任务，重载照常执行、**不打断**该回合（与已废止的重建路径相反——后者在同样情形下必须保持旧配置）；重载以同一 `sessionId` 就地换装、消息与转录连续、不丢消息。
* **不做惰性重建、不提供持久可见标识**：插件变更后的任何时刻（含用户敲过 `/reload-plugins` 之后）**host 不登记任何「待重建」待办、会话/pane 再次被激活时不得自动重建**；新建会话直接按磁盘当前的插件状态装载。变更与重载都只经**一次性提示**告知（两份逐字文案见 [plugin.md](../ecosystem/plugin.md)「插件变更提示」）——**不提供持久可见标识**（2026-09-10 拍板：不新增状态条/角标/列表标记，也不提供「查看哪些对话待应用」的入口——此为刻意取舍，非遗漏）。
* **落盘边界（不进会话）**：桌面端独有的两条本地偏好——**`theme`（主题）与 `updateChannel`（接收 Beta 版更新）**——仍保留在桌面自己的 `wave-desktop.json`（经 host 直连 `setThemeSource`/`setUpdateChannel` 持久化），**不写入** `~/.wave/settings.json`、**不进入**会话配置（选择即时生效、不依赖「保存」按钮）；`serverUrl` 等连接级字段同样不进用户偏好文件。
* **三端一致（2026-09-10 追加拍板：三端同批落地）**：VSCE / JetBrains / desktop 三端设置页的保存路径同语义（均写用户级 `~/.wave/settings.json` 经实时重载生效，均不把用户偏好当 `AgentOptions` 覆盖层下发），以防多端行为漂移（见 [agent-config.md](../core/agent-config.md)「插件端配置入口」）；插件端不再经 `updateAllSessionsConfig` 重建会话生效，本轮与桌面端同批实现。用户在 IDE 内连远端时（VS Code Remote/SSH、JetBrains 远程），写入的是**会话所在进程**的用户级 `~/.wave/settings.json`（远端机器上的该文件），语义与本地一致。**2026-09-18 起不再有「重建确认框」这个桌面端例外**：插件变更一律走就地重载、三端同语义（见 [plugin.md](../ecosystem/plugin.md)「插件变更的就地重载」），既没有「等重建才回执」的症状，也没有需要选择时机的确认框（见 [agent-config.md](../core/agent-config.md) 边界说明「重建确认框已废止」）。
* **旧宿主存储不迁移 + 语言默认值不在宿主侧注入（2026-09-10 追加）**：改造前 `wave-desktop.json` 曾存过 `language` / `contextLength` / `autoMemoryEnabled` / `autoMemoryFrequency`（VSCE 在 `globalState`、JB 在 `wave.xml`）——这些键**不再被读取**，且**不做一次性迁移**（取舍与升级影响见 [agent-config.md](../core/agent-config.md) 边界说明「升级用户的一次性迁移：不做」）：升级后旧值静默失效、回落默认（语言 `zh-CN`、其余 SDK 既有默认），用户需在设置页重选一次。同时 `getConfiguration()` 不得再注入 `language: "Chinese"`（改造前的宿主兜底已删除）：语言默认值只在 SDK 解析链末尾有一处（`zh-CN`），与设置页下拉默认项同串，保证「未设置时显示 ≡ 生效」（见 agent-config.md 边界说明「语言默认值」）。
* **设置页展示的是生效值，不只是用户文件的值（2026-09-10 追加）**：用户级 `~/.wave/settings.json` 是用户偏好的**落点**，但企业下发的 Remote 组织配置 / 机器环境变量可以盖过它（层序与归因范围见 [agent-config.md](../core/agent-config.md) 边界说明「用户偏好的层与来源」）。因此设置页回填的是**生效值**：宿主把 `getUserSettings` 回包里的用户偏好（含每键来源层 `preferenceSources`）原样并入 `configurationData` 给 webview；来源为 `remote` 的键显示生效值 + 置灰 + 提示「由组织配置管理」（组织策略不可被本地覆盖），来源为 `env`（机器环境变量）的键同样显示生效值 + 一句来源说明、但**保持可编辑**（用户级文件优先级高于 OS 环境变量，在此保存即写进该文件并覆盖环境值），`user` / `default` 的键与改造前一致、无来源说明；键缺失仍表示「无任何提供者」（设置页按未设置态展示），`preferenceSources` 是纯增量字段、老宿主缺它时全部可编辑。本 PR 的归因范围为进程级可达的层（Remote / 用户级文件 / 机器环境变量 / 默认），`project` / `local` 覆盖的如实标注记后续（见 [agent-config.md](../core/agent-config.md) 边界说明「用户偏好的层与来源」）。
* **验证分层（单测 / e2e / 真 host）（2026-09-10 追加拍板）**：本故事与「设置页面」故事中「保存不重建」的验收要求，按三层落地——**单测**（`packages/desktop/tests`，宿主被 mock）验证宿主自己发出的命令与状态；**e2e**（`packages/webview/e2e`，真浏览器 + 真 webview bundle）验证「保存后输入框仍在、未弹重建确认框」以及插件变更后的提示与敲 `/reload-plugins` 的交互（不弹任何确认框）；**真 host**（`packages/desktop/tests/integration`，真 `DesktopHost` + 真 `wave --stdio` + 真文件系统，`pnpm -F wave-desktop test:realhost`）验证保存后**真 CLI 进程未被重启（`sessionId` 不变）、会话不丢、`settings.json` 被真实写入且下一轮读到新值（language 一例）、插件变更的就地重载（敲 `/reload-plugins` 后同一 CLI 进程 sessionId 不变、七类能力就地生效、会话未被重建）**；watcher 门禁（启动时文件不存在）与轮内快照等只能由 SDK 单测覆盖的场景在对照表中逐个标明未落到真 host 的原因。逐条对照表见 [agent-config.md](../core/agent-config.md) 边界说明「验证分层（单测 / e2e / 真 host）」。真 host 层挂在 main-only CI job（Linux `real-host-e2e`；Windows `check-windows` 同样跑真 host 与 desktop 单元套件），e2e 层在 PR CI 中为跳过项（非门禁）。

## 边界情况

* **无差异不写盘（2026-11-04 收窄）**：用户偏好值与当前生效值相同（未改任何值，或拨回原位）时**不发报文、不落盘、不弹提示**，但即便真发生同值写入也**不重建**任何会话、不清空排队消息（≠ 配置变更）。

* **未敲 `/reload-plugins` 的后果**：插件类变更落盘后不做任何自动重建、也不自动重载；既有对话持续用旧配置，**新建对话**按新配置生效；用户若要让某个既有对话用上新配置，敲 `/reload-plugins` 即可（无需新开对话）。不因重启客户端之外的无关操作而静默改变行为。

* **重载与流式/权限并存**：敲 `/reload-plugins` 时会话若正在生成回复、存在待确认权限或运行中后台任务，**重载照常执行、不打断该回合**（与已废止的重建路径相反——后者在同样情形下不得重建该会话）。

## 非目标（明确排除）

* **设置页其余 2 个导航项的完整功能**：钩子/MCP 服务本批仅占位（「即将推出」），不提供可编辑控件。

* **设置页在插件端的高保真容器差异**：VSCE/JetBrains 的设置标签页 webview 内容与 desktop 设置页一致，但容器（编辑器区域标签页）为宿主自身形态，不做 desktop 全页面式布局。

* **用户偏好不落桌面本地配置**：设置页「全局设置」/「个性化」的用户偏好不写入桌面 `wave-desktop.json`、不作为 `AgentOptions` 会话级覆盖项下发，落点唯一为用户级 `~/.wave/settings.json`（`theme`/`updateChannel` 例外：仅存桌面 configStore，不进会话）。

* **保存不涉及会话重建的实现机制**：本规格只约束「保存路径与生效时机」的外部行为（立即回执、不重建、必要时确认），不规定 SDK 侧热重载的内部实现（监听/快照等属 agent-config 规格范围）。

* **「待应用」的持久可见标识**：插件变更后不提供常驻标识（无状态条、无列表角标、无会话标记），仅一次性提示（桌面端为「插件已变更，重新加载后生效」确认框，见 [plugin.md](../ecosystem/plugin.md)「插件变更提示」）；不提供「查看哪些对话待应用」的入口与查询面，也不做惰性重建（2026-09-10 拍板；2026-09-18 后「待应用」即等于「等用户敲 /reload-plugins」）。