企业官网建设流程全解析

DeepSeek-Reasonix 会话体验（Session Experience）完全指南：standard/deep 双模式、配置权威与兼容迁移

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

DeepSeek-Reasonix 桌面端通过"会话体验"这一统一设置，控制会话过程中 AI 工作过程的展示策略，将其收敛为standard（标准）与deep（深度）两种完整阅读方案。本文以 docs/SESSION_EXPERIENCE.zh-CN.md 为主线，结合后端配置实现、桌面 RPC 入口、前端展示层与测试用例，讲解两种模式的差异、配置方式、后端权威语义、旧字段兼容映射，以及手动展开状态的生命周期，帮助你在配置、集成与升级中准确掌握该特性的行为边界。

会话体验是什么：统一的工作过程展示策略

在桌面设置中，"会话体验"不再是一堆彼此独立、容易互相矛盾的开关，而是一套二选一的完整阅读策略。从源码注释可以确认其设计意图——internal/config/session_experience.go中的类型定义明确写道：

SessionExperience is the single user-facing desktop presentation preference. It intentionally combines the old transcript density, reasoning display, and process-fold controls into two complete reading strategies.

也就是说，它把旧版的"转录密度"（transcript density）、"推理展示"（reasoning display）和"过程折叠"（process-fold）三组独立控件，合并为两个完整的展示策略，解决旧设置项组合起来语义混乱的问题。

两种模式对工作过程展示的影响如下：

在前端实现中，两种模式被解析为结构化的展示策略。desktop/frontend/src/lib/sessionExperience.ts中的resolveWorkProcessPresentation清晰揭示了二者的唯一差异点：

export function resolveWorkProcessPresentation(value: SessionExperience): WorkProcessPresentation { return { experience: value, showWhileRunning: true, // 运行期间始终展示 keepExpandedAfterCompletion: value === "deep", // 完成后是否保持展开 }; }

两个模式在运行期间都展示正在进行的工作；区别集中在完成后已折叠工作是否保持展开：标准模式默认折叠、可手动展开；深度模式保持展开、可手动折叠。其余一切行为完全一致。

只改变展示、不改变行为的边界

这是会话体验最重要的语义约束。文档明确指出：该设置仅改变展示方式，不改变模型、推理强度、提供方请求、费用、上下文窗口或已保存的会话数据。

这意味着：

• 切换standard与deep不会影响实际的推理过程，不会改变发送给提供方的请求内容，也不会改变计费；
• 上下文窗口管理、会话保存逻辑均与此设置无关；
• 消息内手动展开或折叠属于阅读操作，只影响当前读者的查看方式，不会修改全局设置；
• 警告、审批等需要用户操作的内容仍然可访问——折叠展示不会把需要交互的内容藏起来。

后端 RPC 层的注释同样印证了这一点，见 desktop/reasoning_display_app.go：// SetReasoningDisplayMode persists presentation only; no controller rebuild is needed.——写入该偏好仅持久化展示层设置，不需要重建控制器，进一步说明它不触碰任何运行时逻辑。

配置方式：后端配置是权威来源

会话体验的后端配置位于[desktop]段：

[desktop] session_experience = "standard"

• 合法值仅两个：standard、deep；
• 缺失或无效时使用标准模式（见下文源码规范化逻辑）；
• 后端配置及其设置、启动快照是权威来源；
• 前端字段在一个完整发布周期内保持可选，以兼容旧后端；
• 本地存储不能覆盖后端快照。

后端权威的源码实现

internal/config/session_experience.go的DesktopSessionExperience()是规范化入口：

const ( SessionExperienceStandard SessionExperience = "standard" SessionExperienceDeep SessionExperience = "deep" ) func (c *Config) DesktopSessionExperience() string { switch strings.ToLower(strings.TrimSpace(c.Desktop.SessionExperience)) { case string(SessionExperienceDeep): return string(SessionExperienceDeep) case string(SessionExperienceStandard): return string(SessionExperienceStandard) default: return string(SessionExperienceStandard) // 缺失/无效 → standard } }

它做了两件事：一是对输入做ToLower + TrimSpace归一化，容忍大小写与空白差异；二是任何无法识别为deep的值一律回退到standard——包括缺失值与无效值，绝不会让脏数据产生不可预期的展示效果。

桌面端启动时，desktop/reasoning_display_app.go的desktopStartupSettingsFromConfig会把该值放入启动快照（DesktopStartupSettingsView.SessionExperience，见 desktop/reasoning_display_app.go），前端据此完成初始渲染。

前端的水合（hydrate）与归一化

前端在desktop/frontend/src/lib/sessionExperience.ts中同样实现了"非 deep 即 standard"的防御性归一化：

function normalize(value: unknown): SessionExperience { return value === "deep" ? "deep" : "standard"; }

hydrateSessionExperience(value)只在后端快照到达后才将本地状态置为有效值；在快照到达之前，getSessionExperience()返回安全默认值"standard"，而不会从本地存储中复活旧版本前端写入的过期值（源码注释明确说明此设计，见 sessionExperience.ts）。这正是"本地存储不能覆盖后端快照"的落地实现。

两种模式的展示效果与阅读策略

标准模式（standard）：聚焦当下，完成后自动收敛

• 运行期间：展示正在进行的工作，让你看到 Agent 正在做什么；
• 完成后：已完成的工作默认折叠为摘要形态，界面保持整洁，聚焦于最终结果；
• 读者可以手动展开任意折叠的工作过程，回看细节；
• 适合以结果为导向、关注最终交付物的日常使用场景。

深度模式（deep）：全程直播，细节始终可见

• 运行期间：实时展示完整工作过程，每一步都可见；
• 完成后：所有过程保持展开状态，可手动折叠；
• 适合需要逐条审计、复盘 Agent 每一步动作的场景，例如调试、教学、审查或演示。

前端组件通过useWorkProcessPresentation()/useSessionExperience()等 React hooks（见 sessionExperience.ts）订阅该偏好并应用到消息、推理面板、转录区等展示组件，例如Message.tsx、AssistantReasoningPanel.tsx、Transcript.tsx等。

兼容与迁移：旧入口、旧字段与本地存储镜像

会话体验引入时，旧版本有一套独立的入口与字段。为了平滑降级兼容，项目保留了一个完整发布周期的迁移层。

旧 RPC 入口的映射

桌面 RPC 层保留了三个旧入口（见 desktop/reasoning_display_app.go）：

对应源码：

func (a *App) SetReasoningDisplayMode(mode string) error { return a.applyConfigOnly(func(c *config.Config) error { if mode == "expanded" { return c.SetDesktopSessionExperience(string(config.SessionExperienceDeep)) } return c.SetDesktopSessionExperience(string(config.SessionExperienceStandard)) }) }

旧过程折叠值的映射

旧版"过程折叠"字段的取值expanded、auto分别映射为：

• expanded→深度模式（完成后保持展开）
• auto→标准模式（默认折叠）

写入时的旧字段同步

写入新配置时，后端会同步维护旧字段，保证旧版本客户端仍能读取（见 internal/config/session_experience.go）：

测试 session_experience_test.go 对这一同步行为做了参数化验证：standard → auto、deep → expanded，并断言非法值（如"invalid"）会被拒绝并返回错误。

后端旧字段的读取侧同样以新字段为准：DesktopReasoningDisplayMode()在session_experience有效时直接推导——deep返回expanded、standard返回auto（见 internal/config/reasoning_display.go），只有新字段缺失时才回落到旧字段解析。

旧配置的默认迁移

对于仅含旧字段的配置（如display=compact/minimal、reasoning=hidden/summary/auto/expanded），迁移规则是一律解析为standard——新设置不会继承旧独立标志的组合，避免产生令人意外的展示效果。这在DesktopSessionExperience()的 default 分支中实现，并由 session_experience_test.go 的TestDesktopSessionExperienceDefaultsAndLegacyMigration覆盖验证。

本地存储镜像与旧版本互写风险

前端写入新配置时，会同步维护本地存储镜像（见 sessionExperience.ts）：

localStorage.setItem("reasonix-session-experience", next); localStorage.setItem("reasonix-display-mode", "standard"); localStorage.setItem("reasonix-process-fold", next === "deep" ? "expanded" : "auto"); localStorage.removeItem("reasonix-reasoning-summary"); // 旧布尔汇总键无法表达 deep，避免复活矛盾值

同时还会派发兼容性事件（reasonix:process-fold、reasonix:reasoning-display-mode），让旧版监听器能够感知变化。

需要特别注意的是：旧版本写入配置时可能丢弃它不认识的新字段。因此不保证新旧版本同时写入时无损保留新设置。兼容字段、入口、事件和本地存储镜像应在"下一完整版本发布且不再要求降级兼容"之后再移除。

手动展开状态的缓存与生命周期

用户在消息内手动展开/折叠属于阅读操作，但其状态需要跨渲染与窗口回收保留。文档明确了这一状态的存储策略：

• 键：以"会话 + 稳定过程段标识"为键（不会因为重新渲染而丢失归属）；
• 存储：保存在有界内存缓存中（有容量上限，避免无限增长）；
• 生命周期：可跨渲染和窗口回收保留，但不会跨应用重启持久化——重启后回到模式默认值（标准模式折叠、深度模式展开）。

这一设计将"全局偏好（持久化）"与"阅读位置状态（会话级）"清晰分离：偏好决定默认展示，手动调整只影响当前会话的阅读体验，不会污染全局配置。

验证与测试

除前述单元测试外，前端还配套了覆盖该特性的测试，包括：

• session-experience-settings.test.tsx：设置界面的切换与持久化行为；
• session-experience.test.ts：前端归一化、水合与事件派发；
• settings-refresh-snapshot.test.tsx：设置刷新时快照一致性；
• message-reasoning-panel.test.tsx：推理面板在两种模式下的展示；
• startup-settings-contract.test.ts：启动设置契约（后端快照权威性）。

配置层则有 TOML 渲染往返测试TestDesktopSessionExperienceRenderRoundTrip，验证session_experience = "deep"写入后经RenderTOML再解析仍能保持语义（见 session_experience_test.go）。

总结：会话体验的正确使用姿势

• 在桌面设置或[desktop] session_experience = "standard" | "deep"中配置，缺失或非法值一律回落standard；
• 该设置只影响展示：不改模型、推理强度、请求、费用、上下文窗口与会话数据，警告与审批始终可访问；
• 后端配置与启动快照是权威，前端字段兼容旧后端，本地存储不可覆盖后端快照；
• 旧入口SetReasoningDisplayMode("expanded")映射深度模式，其余旧入口映射标准模式；写入新配置时同步维护旧字段display=standard与reasoning=auto|expanded，支持旧版本读取；
• 手动展开状态以"会话 + 稳定过程段"为键存于有界内存缓存，可跨渲染保留但不跨重启持久化；
• 兼容层（字段、入口、事件、本地存储镜像）在下一完整版本发布且不再要求降级兼容后移除。

对于大多数日常使用，standard模式足以在结果导向的界面中保持整洁；需要完整审计 Agent 每一步工作过程时，切换deep模式即可获得全程展开的实时视图。

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix