DeepSeek-Reasonix 全窗口管理页（Trash / Automation / Settings）架构与实现指南

DeepSeek-Reasonix 全窗口管理页（Trash / Automation / Settings）架构与实现指南

【免费下载链接】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 桌面端的管理页体系展开：Trash（回收站）、Automation（自动化任务）与 Settings（设置）如何共享ManagementPageShell外壳、由useAppNavigationStore统一导航，以及自动化草稿在useAutomationDraftStore中的合并、冲突与操作版本机制。你会掌握这套"全窗口管理页"的导航状态机、草稿生命周期、布局兼容策略与质量验证基线，并可直接在源码中对照每个结论。

1. 设计骨架：一个外壳，三类入口

管理页的设计目标是：不改变原生窗口行为，不打断后台工作，不引入第二个 transcript 滚动写入者。三页（Trash、Automation、Settings）各自保留独立入口，却共享同一个ManagementPageShell外壳——它填充应用窗口、让工作区保持挂载但处于惰性（inert）状态，同时完全保留原生全屏、最大化、关闭行为。

从 ManagementPageShell.tsx 可以看到外壳的实现要点：

• 每个页面都是management-screensection，通过hidden/inert属性控制激活与否；
• 通过active属性，在页面激活时把焦点放到Back（返回工作区）按钮（useLayoutEffect+preventScroll），保证键盘用户进入管理页后焦点位置明确；
• actions插槽承载页级操作（如 Trash 的刷新与清空按钮），navigation插槽支持带侧边栏的布局（如 Settings）；
• 顶部management-screen__chrome是拖拽区（draggable chrome），而按钮与内容区不可拖拽，保证窗口拖动与控件点击互不冲突。

每条功能按需懒加载（lazy chunk）：某个 chunk 加载失败时，用户可以重试或直接退出页面，不会拖垮整个应用。

2. 导航状态机：useAppNavigationStore

2.1 状态与职责

导航统一由useAppNavigationStore管理（appNavigation.ts）。它的职责覆盖：workspace / settings / trash / automation 四类页面切换、最后一个设置的分类（lastSettingsTarget）、焦点恢复（workspaceFocus）、以及唯一的自动化会话返回目标（automationReturn）。

export type AppPage = | { kind: "workspace" } | { kind: "settings"; tab: SettingsTab } | { kind: "trash" } | { kind: "automation" };

关键动作与语义：

• openPage(page)：切换页面，同时递增generation（导航代数），记录上次访问状态，并在离开工作区时保存当前活动元素作为workspaceFocus；
• returnToWorkspace()/enterConversation()：统一回到 workspace 页面；
• setSettingsTarget(tab)：切换设置分类，传null则返回工作区；
• returnFromAutomationLink(generation)：带代数守卫的返回——只有generation仍然匹配时才把页面切回 workspace 并置位automationReturn，避免一次过期的导航把用户"劫持"回工作区。

从状态结构看，visitedTrash/visitedAutomation用于记录是否访问过对应页面，lastSettingsTarget默认值为"general"，即首次进入设置时落到常规分类。

2.2 工作区的"冻结但不卸载"

管理页激活时，工作区保持挂载在原有尺寸，但进入惰性状态。核心实现在 useManagementWorkspace.ts：

• 页面激活时给工作区 DOM 节点设置inert = true，阻断其全部交互输入；
• 离开管理页时恢复inert = false，并通过queueMicrotask在下一轮微任务中把焦点交还给之前触发的那个元素（前提是该元素仍连接在文档中且不在任何 inert 子树里）。

因此返回工作区不会重新激活当前对话、不会重载历史、也不会引入另一个 transcript 滚动写入者——后台任务继续运行，前台输入被干净地隔离。workspaceFocus由openPage在"从 workspace 切换到管理页"的那一刻捕获document.activeElement获得。

2.3 快捷键的"内外有别"

管理页下的键盘策略是分层的：

• Escape：关闭子级菜单/对话框（不退出页面本身）；
• 关闭标签页快捷键（如 Windows 的 Ctrl+W / macOS 的 Command+W）：直接返回工作区；
• 隐藏的工作区快捷键被挂起：即在管理页中不再响应工作区专属的快捷键；
• 命令面板（command palette）、设置与显式会话导航仍然可用。

键盘隔离逻辑可在 keyboardShortcuts.ts 与导航相关测试（management-shortcuts.test.tsx、management-navigation.test.ts）中追踪验证。

2.4 自动化链接触发与会话返回

打开自动化任务关联的对话走的是既有"受保护导航队列"（guarded navigation queue）。成功则显示Back to automation；失败则编辑器保持可见。更晚发起的导航会使更早的结果失效（returnFromAutomationLink的代数守卫正为此设计）。如果用户主动切换项目/会话，临时的返回目标会被清除，避免回到一个已不存在的上下文。

3. Trash：回收站的双栏列表与确定性操作

3.1 宽布局与系统恢复副本

Trash 采用宽布局：左侧为搜索、范围/日期过滤与分组后的会话列表，右侧为只读预览。系统恢复副本（recovery copies）在列表中单独折叠展示（recoveryCopy标记），不会与普通删除的会话混在一起。普通历史（history）沿用既有对话框，并复用同一套列表/预览实现（HistoryPanel以presentation="page"和kind="trash"复用，见 TrashPage.tsx）。

3.2 选择、预览竞态与加载失败

• 选择使用稳定路径（path），一次删除/恢复操作后会前进到最近剩余的相邻行；
• 预览请求带代数计数（seq）：迟到的预览响应不会覆盖更新的选择结果；
• 加载失败与空结果是两种不同状态——失败时展示loadFailed通知与重试按钮（Could not load. Please retry.），空列表则正常显示空态。

3.3 恢复与彻底删除的异步语义

永久删除前必须确认，且初始焦点落在 Cancel（防止误删）。批量"清空回收站"（Empty Trash）会快照每一个普通删除的会话——包括被过滤条件隐藏的行——并排除系统恢复副本。批量执行的特征：

• 顺序执行（非并发），单个失败不中断后续；
• 执行后汇报总数（成功/失败计数），并提供仅重试失败项的显式按钮（Retry failed items，见 managementLocale.ts 中的retryFailed文案）；
• "操作成功但刷新失败"会被单独报告——这样成功的破坏性操作不会被重复提交，避免二次删除已恢复/已删除的会话。

批量逻辑由 trashOperations.ts 的purgeTrashBatch承担，TrashPage 通过mutate(paths, kind)在恢复（restore）与清除（purge）之间共用同一套流程。

4. Automation：草稿存储与调度配置

4.1useAutomationDraftStore的内存态

自动化任务的编辑态由useAutomationDraftStore管理（automationDrafts.ts），每个任务（HeartbeatTask）对应一条AutomationDraft：

export type AutomationDraft = { baseline: HeartbeatTask | null; // 进入编辑时的基线（服务端已保存版本） draft: HeartbeatTask; // 当前可编辑值 conflicts: Field[]; // 冲突字段列表 missing: boolean; // 任务已被外部删除 busy: boolean; // 有操作在途 error: boolean; // 最近操作失败 version: number; // 操作版本（乐观并发） frequency: HeartbeatFrequencyType; // interval / cron / daily / weekly ... tab: "configuration" | "history"; // 详情页签 };

草稿按per-ID保留在内存中：切换任务、切换过滤器、翻页、开关详情、跳转关联会话都不会丢失编辑内容。新增未保存的任务保持可发现（可再次进入编辑），已修改的存量任务显示Unsaved徽标。automationDraftDirty通过对比draft与baseline的可编辑字段判断是否需要显示该徽标。

可编辑字段是白名单式的，见 automationDrafts.ts 中automationEditableFields常量：

["title", "prompt", "interval", "enabled", "scope", "workspaceRoot", "approvalMode", "newConversationEachRun", "notifyChannels", "timeWindowStart", "timeWindowEnd"]

生命周期边界：重新加载 webview 或退出进程会清空草稿；最小化窗口/隐藏到托盘不会清空草稿。

4.2 保存、运行与删除的语义

• 只有 Save 会提交调度配置；保存失败时保留用户输入（finish在失败时仅复位busy并置error）；
• 待处理操作（pending operation）会锁定当前任务（busy），但不阻止导航到其他任务；操作完成也不会抢占选择（通过version守卫）；
• Discard：恢复最新基线（baseline）或删除一个未保存的新任务；
• Run now：使用已保存的配置运行；
• enable/pause：只更新 enabled 字段；
• 删除确认：停止未来的调度，但保留既有会话记录。

4.3 合并、冲突与操作版本

Automation 的底层数据仍在"既有串行变更队列 + revision/etag 检查"框架内，草稿层在此之上做合并：

• Engine 拥有的运行字段（如lastRunAt、runHistory、topicId）合并时不会覆盖用户编辑（reconcileAutomationDraft直接采用远端值并保留草稿）；
• 互不重叠的外部配置变更自动合并（本地未改的字段同步为远端值）；
• 冲突字段（本地与远端都改了同一字段且值不同）阻止正常保存，UI 提供Reload latest或Save as a new paused task两个出口；
• 外部已删除的任务：草稿标记missing且可恢复（保留草稿，不复活原 ID）；
• 新任务 ID 冲突：分配另一个 ID；
• 结果绑定任务身份与操作版本：begin(id)返回递增的version，finish/settle只有在entry.version === version时才生效，天然屏蔽过期响应。

5. 布局与兼容性

5.1 标题栏与两栏布局

• 共享标题栏在macOS 保留 44px、Windows 保留 48px（Windows 原生 46px 控件继续存在），由 CSS 变量--management-titlebar-height表达，可在 settings-responsive-layout.test.ts 与 automation-surface-layout.test.ts 中看到断言；
• 稳定 chrome 区可拖拽（drag），控件与内容区不可拖拽；
• ≥960px宽度时，列表与详情采用双栏：列表最小 280px、详情最小 420px；
• 窄窗口在列表与详情之间切换，不丢失输入；
• Trash 默认列表占比34%；Automation 恢复用户上次保存的宽度偏好，否则使用40%；
• 内容区独立滚动，主操作按钮（Back / Refresh / Clear）始终可见。

5.2 多语言与主题

管理页新增文案集中在 managementLocale.ts，覆盖简体中文、繁体中文、英文三种语言，采用[zh, zh-TW, en]三元组结构（如loadFailed、clearTitle、batchResult、retryFailed等键）。主题直接复用既有 theme tokens，浅色/深色主题自动生效。

无需任何配置迁移：不涉及模型、提示词、工具或缓存协议的变更——这是管理页落地时对既有系统零侵入的设计约束。

6. 验证基线（2026-09-05）

6.1 确定性测试与全量前端套件

验证覆盖了文档中承诺的全部行为，且全部为确定性测试（无随机/时序抖动）：导航代数、草稿合并/冲突/删除、保存期间切换任务、失败路径、键盘隔离、预览竞态、恢复副本排除、部分删除、成功后刷新失败。当时全部 264 个前端套件通过，包括 heartbeat / history / settings 相关套件；独立的 transcript 回归命令同样通过。类型检查与 Hooks / CSS / layer / theme / WAAPI / single-scroll-writer 检查均基于生产构建（production build）执行。

6.2 Windows 与 macOS 实测

• Windows 浏览器预览在1280×900与800×800两个分辨率下实测，覆盖模型设置、回收站确认/取消、草稿/详情保持；全程未清除任何真实会话、未执行任何自动化任务；
• **macOS 原生构建（隔离环境）**验证了页面进入、Escape、Command+W 返回、最小化/恢复、窗口缩放；集成标题栏双击最大化与再次双击恢复原始尺寸也已验证；
• Windows ARM64构建并启动成功（隔离数据，Win11），显示 onboarding；
• 尚未验证项明确标注：原生 Windows 交互、100%/125%/150% DPI 检查未完成，且浏览器预览不能替代原生验证。

6.3 包体积预算

• 初始 payload 约465.4 KiB gzip JavaScript、2480.9 KiB raw JavaScript/CSS；
• 对比集成 main-v2 基线的464.7 / 2481.7 KiB；
• gzip 上限465.5 KiB，上游 raw 上限保持2481.7 KiB；繁体中文 chunk 按61.7 KiB上限取整；
• 功能主体保持懒加载，其余体积预算继续强制生效。

6.4 凭据缓存防护

未保存凭据（unsaved credential）的发现使用瞬态能力解析器（transient capability resolver），不会污染已保存的能力缓存——这是对providerSettingsProbe一类探测逻辑的隔离设计，避免临时探测结果被持久化为能力快照。

7. 源码导航速查

8. 小结

DeepSeek-Reasonix 的管理页体系用"一个共享外壳 + 一个导航状态机 + 一个草稿存储"化解了三类页面的复杂度：工作区通过inert冻结而非卸载，后台任务持续运行；自动化草稿用 baseline/draft/version 三角关系做到不丢输入、不丢状态、不误提交；回收站则用稳定路径、代数守卫与失败单独重试保证破坏性操作的确定性。无论是接入新的管理页类型，还是排查导航/草稿相关问题，上述源码路径都能作为直接起点。

【免费下载链接】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