goodbuddy/docs/features/application-tool-navigation/logic-design.md

应用导航与系统工具入口功能逻辑设计

文档信息

项目	内容
状态	应用中心与本机推理已接入源码，整体验收待完成
版本	0.4
日期	2026-09-17
关联 PRD	应用导航与系统工具入口 PRD
关联 User Stories	User Stories

1. 不变量

1. “当前对话”“运行记录”和“设置”始终是系统入口。
2. 运行记录不进入工具注册表、应用显隐设置或插件市场。
3. 文件浏览器、终端、浏览器和资源监控始终是系统工具，不能卸载或被插件替换。
4. 左下角提供应用中心和独立固定设置入口；文件、终端、浏览器、资源监控只通过右侧工作栏 Tab 和“+”访问，不进入应用中心。
5. 魔法笔记、本机推理的启用、常驻及顺序是独立状态。知识库和智能心跳始终启用并固定显示，不参与这些状态；取消可选应用常驻不关闭功能，关闭不删除数据或导航偏好。
6. 入口不能扩大执行空间、文件、PTY、网络或浏览器权限。
7. 应用中心始终可达，点击向上展开无模态遮罩的锚定菜单，只列已启用应用，不使用打开历史或常驻过滤。菜单底部“管理应用”打开既有 Modal，关闭的可选应用在其中仍可搜索、配置和重新开启。
8. 所有入口和新请求的功能判断读取同一份保存成功的权威设置；保存中的目标值不提前生效。

2. 入口模型

type NavigationContribution =
  | {
      type: 'system-entry'
      id: 'chat' | 'activity' | 'application-center' | 'settings'
      placement: 'primary-start' | 'primary-end' | 'footer'
    }
  | {
      type: 'application'
      id: 'knowledge' | 'heartbeat'
      source: 'builtin'
      fixed: true
    }
  | {
      type: 'application'
      id: 'magic-notes' | 'local-inference'
      source: 'builtin'
      enabled: boolean
      pinned: boolean
    }
  | {
      type: 'system-tool'
      id: 'workspace' | 'terminal' | 'browser' | 'resources'
      workbarAppId: 'workspace' | 'terminal' | 'browser' | 'resources'
    }

该模型是首期的逻辑投影，启用值来自各应用的唯一业务配置，常驻及顺序来自导航偏好。 应用清单为魔法笔记、知识库、智能心跳、本机推理，打开无需安装。市场不加入本轮清单。

3. 主导航组合规则

主导航按以下顺序计算：

当前对话
知识库（固定显示）
智能心跳（固定显示）
可选应用（按保存顺序，仅显示启用且常驻项）
运行记录

当前对话、知识库、智能心跳和运行记录不参与排序。可选应用默认顺序为魔法笔记、本机推理，默认均常驻。两个固定应用始终位于可选应用之前，过滤可选项不留下空白。 常驻、取消常驻和排序按设备保存，重启后恢复。排序只发生在应用区，不移动固定系统入口。 保存完整可选应用顺序，关闭或取消常驻只过滤主导航，不删除顺序记录；重新开启或常驻时按 该顺序恢复。管理列表编辑完整可选应用顺序；上下移动和拖动共用同一顺序写入，两个固定应用不作为拖动项或目标。

3.1 应用可见性与业务状态

下表仅适用于可选应用。知识库和智能心跳始终可用，管理 Modal 中仅有“打开”，保留原工作区实际配置，不增加通用空设置页。心跳单条计划 enabled 仍按原业务规则控制计划。

常驻偏好	功能启用	结果
是	是	主导航显示，可从主导航或应用中心打开
否	是	主导航隐藏，仍可从应用中心打开，后台和数据保持原状
是	否	主导航、应用菜单和业务入口隐藏，管理 Modal 保留设置，记住常驻及顺序
否	否	主导航、应用菜单和业务入口隐藏，管理 Modal 保留设置，记住未常驻状态

管理 Modal 浏览和搜索包含关闭的可选应用，搜索不修改启用或常驻。轻量菜单仅显示已启用项，点击行先关闭菜单；本机推理打开独立 Modal，其余应用请求主内容区导航。管理 Modal 的“打开”和常驻入口遵守同一规则。打开已启用应用不自动常驻； 取消当前应用的常驻不关闭当前页面或本机推理 Modal。关闭应用后不能从旧入口继续执行新的业务操作。 停用时仍允许管理常驻偏好，界面说明重新开启后才会显示入口。

3.2 关闭应用与恢复

关闭与恢复仅适用于可选应用，知识库页面、会话控件及关联，以及智能心跳入口、页面和计划 enabled 不受可选应用偏好影响。

对象	关闭后的结果	重新开启后的结果
当前已打开应用页或本机推理 Modal	原位置显示“应用已关闭”的不可用状态，提供应用设置恢复入口；保留内容状态及草稿，不强制跳转	恢复可用性；仍打开时恢复内容，已关闭或离开则不自动打开
已在执行的请求及后台操作	沿用功能自身的取消、完成和清理生命周期；本次应用开关不新增取消策略	不自动恢复、中断后重跑或补发任务
数据、常驻及顺序	保留原值，业务入口按启用状态过滤	按保存的常驻及顺序恢复入口，不把未常驻应用自动常驻

知识请求及单个知识库实例停用、配置修改或删除继续遵守知识库自身规则，没有应用级禁用判断。

3.3 魔法笔记设置迁移

魔法笔记设置迁入应用中心的共同设置页；笔记页面定位到同一页，全局设置移除该入口， 编辑同一配置。启用、常驻、显示未完成待办数量分别控制功能、导航和徽标，不保留重复的 “显示魔法笔记入口”开关。

未配置的应用启用、常驻及魔法笔记相关布尔项默认开启；已有明确保存的 false 必须保留。 AI 评论方式和评论形式继续为单选，沿用现有默认值“即时”和“长评 + 要点”，不能解释为 全部模式同时启用。迁移保留既有单选值及业务数据。关闭数量显示只隐藏徽标，不修改待办。

4. 系统工具打开规则

4.1 通用流程

用户展开右侧工作栏
  -> 选择已有 Tab，或从“+”目录选择工具
  -> 已有 Tab 按实例 ID 激活；目录按单实例或多实例策略创建或激活
  -> 把焦点移入面板标题或首个主要控件

若创建失败，工作栏保持展开并在对应能力位置显示错误；主页面和其他工作栏实例不被清空。

4.2 决策表

工具	选择已有 Tab	从“+”目录选择	上下文不可用
文件	激活不可关闭单实例并保留跟随或固定状态	聚焦 workspace；仅迁移或布局修复时补回	跟随模式无有效项目目录或默认工作区时显示修复入口
终端	激活选中的确切实例，保留执行空间和历史状态	每次创建绑定当前执行空间的额外实例	新建时无项目使用本机 Home；SSH 失败保留远端目标与诊断
浏览器	激活选中的确切实例，保留绑定目标和页面	每次创建绑定当前 Conversation 的额外实例	新建时无 Conversation 创建待绑定空实例
资源监控	激活本机 resources 单实例	已存在则聚焦，否则创建	部分指标不可用时显示原因并保留其余指标

选择已有 Tab 不按当前项目或 Conversation 查找替代实例，也不重绑目标。文件的跟随模式 仍按工作栏自身规则更新上下文；固定目标失效时显示该目标的修复状态，不静默回退。 终端 closing、exited、interrupted、failed Tab 保留原状态，选择它们不自动重建。 终端和浏览器通过“+”新建时不按目标去重，不恢复旧快捷按钮的最近匹配实例复用行为。

4.3 选中与状态

工作栏按确切实例 ID 表达 Tab 选中状态，同类型其他实例不能同时显示为选中。“+”是普通 按钮，不是 Tab。主侧栏和应用中心不显示工具选中状态或工具徽标。

徽标优先级为：等待用户处理 > 错误 > 运行中 > 无徽标。同一 Tab 只显示一个视觉徽标， 可访问名称包含完整状态。

资源监控首期不在后台采样，因此不显示负载告警徽标。后台事件不自动展开工作栏或切换 Tab。

4.4 资源采样状态

inactive -> warming -> loading -> live
                              -> partial
                              -> error
live/partial/error -> loading
warming/loading/live/partial/error -> inactive

• inactive：资源面板未处于可见活动状态，没有采样定时器。
• warming：首次进入或停止后恢复，建立 CPU 和磁盘 IO 区间基线；内存仍可立即显示。
• loading：正在请求后续样本；请求未结束时跳过后续时钟触发。
• live：所有首期指标可用，按 2 秒间隔追加样本。
• partial：至少一个指标可用；不可用项携带稳定错误码，其他指标继续更新。
• error：本次没有任何可用指标，保留已有历史；自动时钟或手动操作可以重试。

资源面板为活动实例、工作栏展开且 document.visibilityState 为 visible 时才离开 inactive。 任一条件失效即停止定时器并重置区间基线。历史队列只保留最后 150 个样本；时间间隔较长或 采样失败时保留真实时间缺口，不补零或伪造中间数据。

5. 设置保存规则

应用导航偏好与业务启停使用独立字段，通过同一应用设置保存链路提交。常驻、排序、启用和 魔法笔记设置更新串行执行；前一请求确认前，所有入口中会修改这组设置的控件暂不可操作。 每次只提交本次变更，Main 在最新已保存设置上合并并原子写入；顺序提交完整目标顺序。 持久化成功后由 Store 发布完整权威快照，应用中心、主导航、当前应用页、会话和所有设置入口同步采用，工具配置写入也走同一通知链路。每次重开中心先刷新并锁定修改；较新的设置事件使在途旧读取及旧保存响应失效，不能覆盖新快照。

保存失败时：

• 所有界面保留最后一次确认的配置，包括启用、常驻、顺序、徽标和会话入口；不提前运行关闭或恢复副作用。
• 发起操作的设置行或排序区域显示就地可重试错误，保留焦点及编辑上下文，不重复显示同一错误通知。
• 若响应中断导致保存结果未知，先重读权威设置再开放修改；不能把本地旧值当成回滚成功，也不自动重发变更。

6. 与需求的对应关系

逻辑	PRD	User Stories
固定入口不变量	FR-1、FR-2	US-A1、US-A2
应用常驻和失败恢复	FR-3、FR-4、FR-11、FR-12	US-B1、US-B2、US-B4、US-B5
应用中心、常驻顺序	FR-3、FR-4、FR-5、FR-11、FR-12；PRD 第 8 节	US-B6、US-B7
可选应用启用恢复、知识库和智能心跳固定可用	FR-3、FR-4、FR-12；PRD 第 8 节补充要求	US-B8
魔法笔记迁移及共同配置	FR-11、FR-12；PRD 第 8 节补充要求	US-B9
工具打开决策表	FR-6 至 FR-10	US-C1 至 US-C7
资源采样状态	FR-9	US-C6
无障碍与窄窗口	FR-13	US-D1、US-D2
活动聚合、完成通知与查看清除	FR-14	US-E1、US-E2、US-E3
后续私有市场与 YAML	FR-15	US-F1、US-F2
服务状态、资源可用性、服务生命周期	FR-16	US-F3、US-F5；US-F4 入口已移除

稳定 ID 保留原编号。US-B6 为应用中心，US-B7 为顺序，US-B8 为启用联动，US-B9 为笔记迁移； US-F3 为服务概览，US-F4 为已移除的任务取消入口，US-F5 为服务生命周期。PRD 旧 FR-5 至 FR-10 和 User Stories 已同步上述入口规则，工具实例行为沿用右侧工作栏契约。

7. 逻辑完整性评估

首期覆盖应用中心访问、启用与常驻组合、顺序恢复、默认值与旧值迁移、共同设置、保存失败、 知识库和智能心跳固定入口、可选应用已打开页面恢复，以及右侧实例选择、本机 Home、托管 SSH、无会话、 目录失效、资源部分可用与采样停止。工具内部取消、超时、连接恢复及业务后台生命周期由 相应功能负责，本功能不复制状态机。底部入口打开轻量菜单，“管理应用”才进入与设置相同的整窗 Modal。实现与验证的剩余范围见实施进度。

8. 后续产品决策

后续市场 URL、YAML 交换、ShareServer 目录与分发、插件注册及安装不进入首期。其协议、 扩展身份与安装生命周期由市场功能另行确定；内置应用常驻及排序不依赖这些决策。

8.1 本机推理管理

FR-16 独立于市场排期，作为可常驻的管理 Modal。所有打开入口只改变 Modal 打开状态，不改变底层工作区、项目、会话或草稿；关闭时卸载 Modal，服务生命周期独立。US-F3 只有服务列表，展示名称、状态、引擎、模型及错误。共享服务只展示一次；资源按独立服务进程归属，CPU 预热与指标不可用分别给出原因，不填 0，不将宿主进程占用分摊给共享线程。采样与单位见技术设计。ASR 没有 Worker 就绪观测，显示按需运行且状态未知；活动请求不覆盖服务状态。OCR 状态来自 Renderer Worker，向量状态来自 Broker。

US-F4 的 Modal 单任务取消入口已移除。后端取消行为保留：Worker 确认或退出前仍计入活动任务和停止影响，即使调用方已收到取消或超时错误；任务先完成则保留真实完成结果，不通过终止共享服务模拟单任务取消。

服务管理方式	可提供操作	结果要求（US-F5）
GoodBuddy 受管子进程	引擎已支持的启动、停止、重启	共用同一服务实例；操作成功由真实进程和服务就绪状态确认
外部服务	在模型与连接设置中管理	不列入本机服务，不推断本机归属
进程内模型	引擎实际支持的加载、释放	不显示虚构 PID 或进程启动、停止状态

停止、重启或释放均先打开紧凑的嵌套影响确认，列出任务和影响；无已登记活动任务时说明执行前再次核对。取消确认不改变运行状态。 确认存在时禁止关闭底层管理 Modal；提交期间两层均不能关闭，重复操作被拒绝。未提交时 Escape 只关闭确认，确认关闭后才可用 Escape 关闭管理 Modal。焦点规则由 UI 设计定义。 实际操作失败关闭旧确认、显示错误并刷新快照；刷新期间或失败时禁用服务操作。再次操作重新取得当前任务清单并要求确认，避免重复提交旧清单。 再次启动不重放已中断任务；关闭管理 Modal、关闭管理应用或取消常驻不停止服务，卸载模型文件为独立操作。 当前向量服务允许确认影响后停止，并拒绝确认清单未包含的新任务；OCR 仅空闲时允许释放。 ASR 按请求加载与释放，支持独立取消；TTS 尚无执行服务。具体适配边界以 技术清单为准。活动请求仅在影响确认中展示，主列表不展示历史。应用退出清理沿用各引擎原有路径。

9. 项目活动汇总

对应 FR-14，按 Conversation ID 聚合，每条会话最多一行。 数据来源为活动会话 ID、会话中的流式消息及待回答/待审批请求，以及全部可见的运行中或 等待处理 Task，以及当前应用会话内的已完成未查看集合；不能只取当前项目、当前搜索结果或每条会话的最新 Task。

优先级（高到低）	条件	汇总类别
待回答	消息有待回答问题	待处理
待审批	消息有待审批请求	待处理
Task 等待处理	Task 为 waiting_approval，尚无更具体的消息状态	待处理
运行中	活动会话 ID、streaming 消息或运行中 Task	运行中
已完成	会话在已完成未查看集合中，且无更高优先级实时状态	已完成

同一会话只采用最高优先级状态；Task 的 waiting_approval 也可能对应提问，不能直接 标成待审批。“待处理”“运行中”和“已完成”数量互斥，全局总数为三者之和；项目计数使用相同结果。 项目归属优先取会话元数据，缺少会话时取 Task 元数据；无项目归属的活动只计入全局汇总。

历史排队项、仅待调度的 Task、终态 Task 和普通未读标记本身不构成活动。完成通知规则如下：

• 本地运行收到成功 done，或当前活动运行从持久化快照确认成功完成时，记录会话完成通知。
• 后台顶层 Task 只有在本次应用会话中已观察到该任务，随后状态转为 completed 时才记录通知； 初次载入或首次出现的已完成历史任务只建立基线，子任务不单独产生通知。
• 失败、取消不产生完成通知。实时待处理或运行中状态优先；开始新运行时清除旧完成通知， 已观察 Task 转为 running 或 waiting_approval 时也清除对应会话的旧通知。
• 通知只保存在 Renderer 内存，不跨重载或重启恢复，也不从普通未读状态推导。
• 仅当目标会话实际成为当前聊天、设置未打开且文档未隐藏时清除通知；普通侧栏导航和活动菜单 导航采用同一查看条件。已在查看的会话完成后不保留通知，恢复可见聊天时也清除通知。
• 展开活动项目、查看菜单、设置覆盖下保留挂载的聊天、隐藏文档以及取消设置离开都不算查看。

没有实时状态且没有已完成未查看通知时才移除活动行。

级联菜单先按项目归属聚合活动行，沿用本地、SSH Host、通道的稳定项目顺序；缺少项目 元数据的归属组及“未归属项目”组放在已知项目之后。无归属组只用于访问这些会话，不增加 项目计数。每个项目内依次列待处理、运行中、已完成会话，同类别保留来源顺序。

展开项目只改变菜单层级，不导航。选中项目的活动行全部移除后返回项目列表；全局无活动行后 关闭菜单并隐藏摘要入口。后台更新保留仍存在的焦点项，删除焦点项时将焦点 移至当前层可用项。关闭菜单后，新的活动只恢复摘要，不会自动重新打开菜单。