CodeWave IDE

Appearance

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

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

用户场景与测试 ​

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

作为用户，我希望通过侧边栏账户卡片菜单（已登录为点击个人信息行热区弹出的纯功能菜单，未登录为「更多」按钮菜单；两态菜单均含「设置」项）中的「设置」打开完整的设置页面，在左侧导航分组中浏览当前生效的全部配置与状态（语言、主题（桌面端）、上下文长度、AGENTS.md、自动记忆、项目插件、技能、子代理、钩子、MCP 服务；桌面端导航里没有「插件市场」——它由侧边栏「新对话」下方的入口打开整页，VSCE / JetBrains 仍以设置页导航项承载，见 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-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「插件变更的就地重载」），本端不弹任何重建确认框。

独立测试：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「插件市场」场景 3 与 A-016），VSCE / JetBrains 没有侧边栏整页、设置页这项是它们唯一入口；浏览类视图不出现编辑控件，「全局设置」「个性化」仅对可编辑项展示控件。
  3. 假设用户点击「全局设置」，当进入该视图，则必须显示两个区块：「基础设置」卡片与「桌面端设置」区块（后者仅桌面端渲染）。「基础设置」卡片展示当前生效的 AI 回复语言（中文 zh-CN / English en-US）与上下文长度（K 值）——补全相关的两行（「代码补全」开关 / 「补全模型」下拉）不在本端展示：桌面端没有代码编辑器、不提供行内补全，这两行只由提供补全的插件端（VS Code / JetBrains）设置页渲染，语义见 code-completion.md 边界情况「补全设置行的宿主范围」；语言为下拉选择（中文/English）、上下文长度为数字输入（16–1000 K，读写同一个全局键 env.WAVE_CONTEXT_WINDOW，行内须给出一句可见说明如「全局默认；当前模型自带上下文上限时以模型配置为准」——2026-09-10 拍板，语义见 agent-config.md 边界说明「上下文长度的落点」），改动即时写盘——没有「保存」按钮（2026-11-04 拍板，见 agent-config.md「设置页控件的保存时机」）；文件里没有该键时不得假装一个有值：语言下拉首项为「未设置（默认：中文）」并选中、上下文长度输入框留空并以灰字占位符「跟随模型配置（默认 200K）」显示系统默认（完整规则见 agent-config.md「插件端配置入口」故事场景 7–8）；被更高层覆盖的键必须如实显示生效值，不得回退显示用户文件里的值、也不得显示「未设置」态（见 agent-config.md「插件端配置入口」故事场景 9 与边界说明「用户偏好的层与来源」）：企业下发的 Remote 组织配置（用户本地无法覆盖）→ 置灰 + 行内提示「由组织配置管理」；机器环境变量给值 → 显示生效值 + 一句来源说明但仍可编辑（保存即写进用户级文件并覆盖环境变量的值）；保存把用户偏好写入用户级 ~/.wave/settings.json（经 SDK 实时重载在各会话下一轮开始时生效，见 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「插件端配置入口」故事场景 7），开关不做占位态（其真实默认即「开」，三态开关更难用）继续显示为开；被更高层覆盖时同样如实显示生效值：Remote 组织配置 → 置灰 + 「由组织配置管理」，机器环境变量 → 显示生效值 + 来源说明但仍可编辑（见 agent-config.md「插件端配置入口」故事场景 9）；保存只写改动过的字段（省略键 = 不改该键）；保存即生效且影响运行中的会话——关闭后从下一轮起不再触发记忆提取（不写入自动记忆文件）、新建会话同样不提取，重新开启后恢复且计数从开启时刻重新累计，频率按新值生效（语义见 memory-management「自动记忆开关」）；保存同样写入用户级 ~/.wave/settings.json、不重建会话（含自动记忆安全区目录随开关热更新，见 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「插件变更的就地重载」），其余内容只读。开关状态每次进入该视图都以当前会话/活动项目的工作目录重新读取，不得沿用上次进入缓存的旧值：会话/工作目录切换后重入视图必须刷新为该工作目录的真实配置；外部变更（手动编辑 .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「设置页控件的保存时机」）；没有改动时不发任何报文，打开设置页、切换导航项、切换视图 tab、关闭设置页本身不得触发任何写入或会话重建。
  12. 假设desktop 处于分屏（多个 pane）或单会话布局且已打开设置页，当查看设置页布局，则设置页必须覆盖整个窗口——会话侧边栏与所有 pane 一并被隐藏，仅设置页可见；分屏的 pane 数量/尺寸/会话不因打开设置而销毁（会话在后台继续运行，含流式输出）；点击「返回」关闭设置页后恢复打开前的布局（分屏 pane 布局、侧边栏展开/收起、聚焦会话、消息滚动位置原样保留），不新建会话、不打断流式。
  13. 假设用户没有改动任何控件（含控件仍处于「未设置」态的情形），或把某个控件拨回/改回与原生效值相同，当停留在设置页、来回切换导航项，则一条写盘报文都不发、不落盘、不弹任何提示——未改动的键一律不出现在载荷里（省略键 = 不改该键，未设置态不写该键，见 agent-config.md 边界说明），也不得重建任何会话、不得清空排队消息、不得打断流式输出。
  14. 假设本次保存只涉及热生效键（AI 回复语言、上下文长度、自动记忆开关/轮次等），当保存完成，则不得重建任何会话；假设本次变更包含插件安装/卸载/启停/更新或内置插件开关，当变更落盘，则同样不得重建任何会话、不得弹任何重建确认框——变更只产生一个「待应用」信号并由宿主提示一次（逐字文案见 plugin.md「插件变更提示」），由用户敲 /reload-plugins 触发就地换装。
  15. 假设用户敲 /reload-plugins，当重载执行，则在同一会话内就地换装、会话 id 不变、消息与转录连续、不打断正在生成的回合；假设用户未敲命令，则不存在任何自动重建路径，也不登记「待重建」待办——变更只对新建对话自动生效（完整语义见 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「后台会话确认提醒」）保持既有右下角通知形态（不带语义图标），不并入顶部新形态，两栈可同屏共存。语义三色只用于设置页结果型提示（AGENTS.md 保存成功/失败、用户偏好写盘失败、删除/移除技能·子代理·钩子·MCP 成功/失败、MCP 连接/断开失败；插件变更的两句一次性提示不在其列——它们按中性提示呈现，见 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「设置实时重载」）。不得把用户偏好经 stdio initialize / updateConfig 当 AgentOptions 覆盖层下发（该层优先级高于 settings.json，会永久遮蔽实时配置，正是此前必须重建会话的根因）。
  • 回执与刷新：写盘的回执（configurationResponse）与界面刷新在落盘后立即给出，不等待任何会话重建；失败提示亦在持久化结果确定时发出（成功不发提示）。
  • 不重建：纯热生效键的写入（无论值有无变化）不重建任何会话——不销毁/重建 live 会话、不清空排队消息、不打断流式输出；值未变时连写盘都不发生（控件与生效值相同即不提交），更不得触发重建与队列清空。
  • 不再有需要重建的构造期副作用：插件装卸（安装/卸载/启用/禁用/更新插件、内置插件开关，如项目设置里的 SDD）2026-09-18 起改为就地重载——变更落盘后不重建会话、不弹任何确认框，由用户敲 /reload-plugins 在同一会话内换装（见 plugin.md「插件变更的就地重载」）；自动记忆开关/频率早在 2026-09-10 改为热生效。至此没有任何配置变更需要重建会话（见 agent-config.md「配置变更不再需要重建会话」故事）。
  • 重建确认框已废止（2026-09-18 拍板）：插件变更 2026-09-18 起改为就地重载，本端不再有任何重建确认框——原先的「立即重启 / 稍后重启」两按钮、N/M 文案、Esc 等同「稍后重启」等条款一并取消。变更落盘后只弹一次「插件已变更，重新加载后生效」确认框（「稍后」/「立即重新加载」），由用户自己决定何时应用（见 plugin.md「插件变更提示」）。
  • 就地重载不打断任何会话：敲 /reload-plugins 时若某会话正在生成回复、有待确认权限（等待用户确认/回答）或存在运行中后台任务，重载照常执行、不打断该回合（与已废止的重建路径相反——后者在同样情形下必须保持旧配置）；重载以同一 sessionId 就地换装、消息与转录连续、不丢消息。
  • 不做惰性重建、不提供持久可见标识：插件变更后的任何时刻（含用户敲过 /reload-plugins 之后）host 不登记任何「待重建」待办、会话/pane 再次被激活时不得自动重建；新建会话直接按磁盘当前的插件状态装载。变更与重载都只经一次性提示告知（两份逐字文案见 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「插件端配置入口」）；插件端不再经 updateAllSessionsConfig 重建会话生效，本轮与桌面端同批实现。用户在 IDE 内连远端时（VS Code Remote/SSH、JetBrains 远程），写入的是会话所在进程的用户级 ~/.wave/settings.json（远端机器上的该文件），语义与本地一致。2026-09-18 起不再有「重建确认框」这个桌面端例外：插件变更一律走就地重载、三端同语义（见 plugin.md「插件变更的就地重载」），既没有「等重建才回执」的症状，也没有需要选择时机的确认框（见 agent-config.md 边界说明「重建确认框已废止」）。
  • 旧宿主存储不迁移 + 语言默认值不在宿主侧注入（2026-09-10 追加）：改造前 wave-desktop.json 曾存过 language / contextLength / autoMemoryEnabled / autoMemoryFrequency（VSCE 在 globalState、JB 在 wave.xml）——这些键不再被读取，且不做一次性迁移（取舍与升级影响见 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 边界说明「用户偏好的层与来源」）。因此设置页回填的是生效值：宿主把 getUserSettings 回包里的用户偏好（含每键来源层 preferenceSources）原样并入 configurationData 给 webview；来源为 remote 的键显示生效值 + 置灰 + 提示「由组织配置管理」（组织策略不可被本地覆盖），来源为 env（机器环境变量）的键同样显示生效值 + 一句来源说明、但保持可编辑（用户级文件优先级高于 OS 环境变量，在此保存即写进该文件并覆盖环境值），user / default 的键与改造前一致、无来源说明；键缺失仍表示「无任何提供者」（设置页按未设置态展示），preferenceSources 是纯增量字段、老宿主缺它时全部可编辑。本 PR 的归因范围为进程级可达的层（Remote / 用户级文件 / 机器环境变量 / 默认），project / local 覆盖的如实标注记后续（见 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 边界说明「验证分层（单测 / 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「插件变更提示」）；不提供「查看哪些对话待应用」的入口与查询面，也不做惰性重建（2026-09-10 拍板；2026-09-18 后「待应用」即等于「等用户敲 /reload-plugins」）。