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

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

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 应用中心与本机推理监控已接入源码，整体验收待完成 |
| 版本 | 0.4 |
| 日期 | 2026-09-17 |
| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
| 关联 User Stories | [User Stories](./user-stories.md) |

## 1. 不变量

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

## 2. 入口模型

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

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

## 3. 主导航组合规则

主导航按以下顺序计算：

```text
当前对话
应用（按保存顺序；知识库始终显示，可选应用仅显示启用且常驻项）
运行记录
```

当前对话、运行记录和设置不参与应用排序。默认应用顺序为知识库、智能心跳、魔法笔记、本机推理监控；魔法笔记默认常驻，本机推理监控默认不常驻。过滤可选项不留下空白。
常驻、取消常驻和排序按设备保存，重启后恢复。排序只发生在应用区，不移动固定系统入口。
管理列表、应用菜单和主导航共用完整应用顺序，分别按搜索、启用、启用且常驻过滤；过滤不删除顺序记录，重新开启或常驻时按保存顺序恢复。
每个管理行均可排序，包括关闭或未常驻的应用。上下移动以完整保存顺序中的相邻应用为目标，拖动使用同一移动规则。搜索时禁用拖动，箭头仍按完整顺序移动，保留未命中应用及其相对顺序。

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

下表适用于智能心跳、魔法笔记和本机推理监控。知识库始终可用，管理 Modal 中提供“打开”和排序，保留原工作区实际配置，不增加启用、常驻开关或通用空设置页。心跳应用的默认值与执行条件见[应用启停与执行](../conversation-supervision/logic-design.md#应用启停与执行)。

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

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

### 3.2 关闭应用与恢复

关闭与恢复适用于可选应用，知识库页面、会话控件及关联不受影响。智能心跳关闭后的调度、手动请求、侧栏与在途运行按[应用启停与执行](../conversation-supervision/logic-design.md#应用启停与执行)处理，保留单条计划 enabled。

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

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

### 3.3 魔法笔记设置迁移

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

未配置的魔法笔记、本机推理监控启用及魔法笔记相关布尔项默认开启；心跳应用默认关闭。魔法笔记和心跳默认常驻，本机推理监控默认不常驻；已启用应用仍可从应用菜单及管理 Modal 打开。已有保存的 `true` 和 `false` 均保留。
AI 评论方式和评论形式继续为单选，沿用现有默认值“即时”和“长评 + 要点”，不能解释为
全部模式同时启用。迁移保留既有单选值及业务数据。关闭数量显示只隐藏徽标，不修改待办。

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

### 4.1 通用流程

```text
用户展开右侧工作栏
  -> 选择已有 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 资源采样状态

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

应用导航偏好与业务启停使用独立字段，通过同一应用设置保存链路提交。常驻、排序、启用和
魔法笔记设置更新串行执行；前一请求确认前，所有入口中会修改这组设置的控件暂不可操作。
每次只提交本次变更，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、US-E4 |
| 后续私有市场与 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。FR-14 覆盖统一菜单的入口与范围、预览与进入、最近条数、状态筛选、通道创建限制及会话期恢复，规则见第 9 节。实现与验证的剩余范围见[实施进度](./progress.md)。

## 8. 后续产品决策

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

### 8.1 本机推理管理

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

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

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

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

## 9. 项目活动汇总

对应 [FR-14](./prd.md#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 用户项目及其活动，消息通道仍可见。

左栏沿用本地、SSH Host、消息通道的项目顺序，主机支持折叠，不按活动数量排序。右栏合并内存会话摘要与活动行，按 Conversation ID 去重；摘要尚未到达的活动仍可显示。无项目归属的会话只在全部项目范围显示，不增加项目计数；已不存在或不可见项目的会话排除，通道项目只显示通道会话。

默认筛选依次列待处理、运行中、最近会话。前两组不限条数且不重复列入最近；组内排序时间取最新消息创建时间与本次应用会话内访问／状态变化时间的最大值，无消息时用会话更新时间参与比较，同时间按 ID 排序，不按置顶优先排序。最近组最多 10 条，已完成未查看会话归入最近组并标注状态；“已完成”筛选列出全部完成未查看会话，不受 10 条限制。

行内显示时间只取会话 `updatedAt`，不使用上述排序时间、访问时间或任务状态变化时间。只有活动而没有会话摘要时不显示时间，也不构造日期或读取详情补齐。流式输出可以更新行内时间，但不因此改变原有排序规则。

首次活动状态快照只建立基线，不更新最近时间；后续状态变化更新时间，唯独从已完成变为无活动的提醒清除不更新时间。实际打开会话仍记录访问时间；悬停预览不记录。访问与状态时间仅保留在当前 Store 内存中，不跨重载或重启恢复。

点击项目经离开检查进入聊天，优先恢复本次应用会话内为该项目记住的有效 Conversation ID，否则按最新消息时间从候选会话中选最近一条，无消息时取会话更新时间。普通项目无会话时创建；通道项目只选通道会话，无会话时显示空态。记忆不跨重载或重启保存。点击会话仍按确切 ID 导航；设置按钮独立，不触发项目切换。“新建会话”使用预览项目，全部项目范围使用当前项目；目标缺失或为消息通道时禁用。

全局无活动时第二行显示“暂无活动”，按钮仍可打开菜单并预览当前项目的最近会话或空态，也可在菜单内切换全部项目范围。活动归零不改变控件高度，也不关闭已打开的菜单。点击外部、焦点离开、Escape 或隐藏侧栏关闭菜单，后台活动不自动打开。查看预览不清除完成通知，实际进入可见聊天才按上述规则清除。

归档视图是左栏列表的临时模式，不新增顶部分类，不改变右栏预览范围。它只列已归档用户项目，保留本地／SSH Host 分组、搜索和远程能力过滤；归档行只有恢复操作，不作为可进入或可预览项目。恢复先同步会话摘要，再让项目回到活动项目集合，保持当前项目、会话和页面。成功后从归档列表移除；失败保留操作入口，可重复提交同一恢复动作。恢复不修改 Task 状态，不重放任务或启动远程连接。

右下角“进入项目”与点击普通项目行共用导航规则，目标为预览项目，全部项目范围回退到当前项目；目标不可用时禁用。归档视图中按钮仍对应右栏原预览，不能直接进入未恢复项目。