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

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

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.2 |
| 日期 | 2026-09-08 |
| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
| 关联 User Stories | [User Stories](./user-stories.md) |

## 1. 不变量

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

## 2. 入口模型

```ts
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. 主导航组合规则

主导航按以下顺序计算：

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

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

### 3.1 应用可见性与业务状态

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

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

## 4. 系统工具打开规则

### 4.1 通用流程

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

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

### 4.2 决策表

| 工具 | 匹配实例存在 | 匹配实例不存在 | 上下文不可用 |
| --- | --- | --- | --- |
| 文件 | 激活单实例并保留其跟随或固定状态 | 创建跟随当前上下文的 `workspace` 单实例 | 打开面板并显示目录修复入口 |
| 终端 | 激活当前执行空间最近的 `starting` 或 `running` 实例 | 创建一个绑定当前执行空间的实例 | 没有项目时使用本机 Home |
| 浏览器 | 激活单实例并保留其目标状态 | 创建跟随当前会话的 `browser` 单实例 | 打开面板并提示选择或创建对话 |
| 资源监控 | 激活 `resources` 单实例 | 创建本机 `resources` 单实例 | 部分指标不可用时显示原因并保留其余指标 |

文件和浏览器按以下优先级处理目标：已有有效固定目标、跟随模式的当前上下文、新实例的默认
上下文。固定目标失效时显示该目标的修复状态，不回退到当前项目、默认工作区或当前会话。

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

### 4.3 选中与状态

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

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

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

### 4.4 资源采样状态

```text
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. 后续产品决策

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

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