root/goodbuddy

Fork 0

Files

T

mesalogo 80b0b18712 feat: add persistent workbar browser tabs and scoped MCP routing

2026-09-10 01:26:56 +08:00

7.1 KiB

Raw Blame History

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

文档信息

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

1. 不变量

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

7. 逻辑完整性评估

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

8. 后续产品决策

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

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

7.1 KiB Raw Blame History