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

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

文档信息

项目	内容
状态	设计中
版本	0.2
日期	2026-09-08
关联 PRD	应用导航与系统工具入口 PRD
关联 User Stories	User Stories

1. 不变量

1. “当前对话”“运行记录”和“设置”始终是系统入口。
2. 运行记录不进入工具注册表、应用显隐设置或插件市场。
3. 文件浏览器、终端、浏览器和资源监控始终是系统工具，不能卸载或被插件替换。
4. 左下角只提供快捷入口，工具内容仍由助手工作栏承载。
5. 隐藏应用不等于停用功能，也不删除、迁移或清理业务数据。
6. 快捷入口不能扩大执行空间、文件、PTY、网络或浏览器权限。

2. 入口模型

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

该模型只覆盖首期入口。插件贡献模型随插件 Host、权限和生命周期另行设计。

3. 主导航组合规则

主导航按以下顺序计算：

当前对话
可见的内置应用
运行记录

当前对话和运行记录不参与排序。首期内置应用默认顺序为魔法笔记、知识库、智能心跳；显隐 设置只从中移除对应项，不改变固定入口的位置。

3.1 应用可见性与业务状态

导航可见	功能启用	结果
是	是	显示入口并允许进入
否	是	隐藏入口，后台和数据保持原状
是	否	不显示不可用入口；设置页保留启用路径
否	否	不显示入口，保留符合该功能自身规则的数据

“功能启用”由各应用现有产品设置负责。例如魔法笔记启停仍使用原设置；导航偏好不能覆盖它。

4. 系统工具打开规则

4.1 通用流程

用户激活工具按钮
  -> 校验按钮仍可用
  -> 向助手工作栏发送打开意图
  -> 工作栏按应用实例策略查找或创建实例
  -> 展开工作栏
  -> 激活目标实例
  -> 把焦点移入面板标题或首个主要控件

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

4.2 决策表

工具	匹配实例存在	匹配实例不存在	上下文不可用
文件	激活不可关闭的单实例并保留其跟随或固定状态	仅在迁移或布局修复时补回 workspace	打开面板并显示目录修复入口
终端	激活当前执行空间最近的 starting 或 running 实例	创建一个绑定当前执行空间的实例	没有项目时使用本机 Home
浏览器	激活绑定当前 Conversation 的最近使用实例	创建绑定当前 Conversation 的新实例	激活最近使用实例；不存在时创建待绑定实例
资源监控	激活 resources 单实例	创建本机 resources 单实例	部分指标不可用时显示原因并保留其余指标

文件保持单一实例原有绑定。浏览器快捷入口按当前 Conversation 匹配最近使用实例，而工作栏 “+”始终新建浏览器实例。固定目标失效时显示该目标的修复状态，不回退到当前项目、默认 工作区或当前会话。

closing、exited、interrupted 和 failed 终端不属于可复用实例。当前执行空间只有这些 终端时，快捷按钮创建新实例并保留原 Tab 的历史状态。用户需要额外的并行终端时使用工作栏 “+”或终端面板中的既有创建命令。

4.3 选中与状态

工具按钮满足以下条件时显示选中：助手工作栏已展开，且当前活动实例的 appId 与工具映射 一致。只有实例存在但未激活时不显示选中。

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

资源监控首期不在后台采样，因此不显示负载告警徽标。只有资源面板是工作栏当前活动实例且 工作栏已展开时，资源按钮才显示选中状态。

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. 设置保存规则

应用导航偏好与应用业务启停分开保存。Switch 每次切换立即提交完整目标集合；请求完成前禁用 三个应用显隐 Switch，下一次操作基于最新确认结果提交，防止并发更新互相覆盖。

保存失败时：

• 主导航和 Switch 恢复最后一次成功保存的偏好。
• 设置行显示可重试错误。
• 不回滚或修改各应用的业务状态。

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-5 至 FR-10	US-C1 至 US-C7
资源采样状态	FR-9	US-C6
无障碍与窄窗口	FR-13	US-D1、US-D2
活动聚合、完成通知与查看清除	FR-14	US-E1、US-E2、US-E3

7. 逻辑完整性评估

首期规则已覆盖固定入口、应用显隐、保存失败、系统工具匹配与显式多实例差异、本机 Home、 托管 SSH、无活动会话、目录失效、资源部分可用、采样停止、权限边界、键盘和窄窗口。其他 工具面板内部的取消、超时、 连接恢复和固定目标失效继续由助手工作栏负责，本功能不复制这些状态机。

8. 后续产品决策

• 插件工具上线后，快捷栏允许固定的最大数量及溢出规则。
• 插件应用是否允许用户排序，以及固定系统入口之间允许的排序范围。

这些决策不影响首期四个系统工具的固定入口和内置应用显隐实现。

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、通道的稳定项目顺序；缺少项目 元数据的归属组及“未归属项目”组放在已知项目之后。无归属组只用于访问这些会话，不增加 项目计数。每个项目内依次列待处理、运行中、已完成会话，同类别保留来源顺序。

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