goodbuddy/docs/features/application-tool-navigation/prd.md

# 应用导航与系统工具入口 PRD

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 应用中心与本机推理监控已接入源码，整体验收待完成 |
| 版本 | 0.4 |
| 日期 | 2026-09-17 |
| 适用产品 | GoodBuddy 桌面端 |
| 关联设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[助手工作栏 PRD](../assistant-workbar/prd.md) |

## 1. 背景

本版已同步应用中心方案，分期见[第 8 节](#8-分期)。左下角用于访问和管理应用，系统工具保留在右侧工作栏。

原主侧栏把“当前对话”“魔法笔记”“知识库”“智能心跳”和“运行记录”放在同一导航组，
底部显示“GB 本地工作区”和平台架构。当前已将底部改为应用中心及独立设置入口，文件、终端
和浏览器继续从右侧助手工作栏打开。

后续插件可能提供完整页面，也可能只提供辅助面板或命令。若不先区分系统入口、应用和工具，
插件接入后会同时争用主导航、侧栏底部和助手工作栏，用户也无法判断入口会切换页面还是打开
辅助面板。

## 2. 产品定义

### 2.1 入口分类

| 类型 | 首期成员 | 默认位置 | 用户控制范围 |
| --- | --- | --- | --- |
| 系统入口 | 当前对话、运行记录、设置 | 主导航固定位置或侧栏底部 | 不可隐藏、卸载或改变类型 |
| 始终显示的内置应用 | 知识库 | 主导航应用区及应用中心 | 始终启用并常驻，可排序，不提供启用或常驻开关；保留工作区实际配置 |
| 可选内置应用 | 智能心跳、魔法笔记、本机推理监控 | 应用中心及主导航常驻区 | 独立控制启用、常驻与排序；保留数据 |
| 系统工具 | 文件浏览器、终端、浏览器、资源监控 | 右侧助手工作栏 Tab 和“+”目录 | 自带且不可卸载，按工作栏规则管理实例 |

运行记录是系统审计页面，不属于工具。文件浏览器、终端、浏览器和资源监控是系统工具；它们
的入口与实际界面均由右侧助手工作栏承载，不列入应用中心。

### 2.2 后续插件类型

插件市场开放后，插件可以贡献“插件应用”或“插件工具”。插件不能注册、覆盖或替换系统入口，
也不能冒充系统工具。内置应用继续标记为“内置”，不因采用统一注册协议而显示成待安装商品。

## 3. 目标

- 用户从侧栏底部进入应用中心，查找、打开和配置内置应用。
- 主导航承载应用入口，本机推理监控打开 Modal，其余内置应用打开完整页面；辅助工具由工作栏承载。
- 运行记录始终可发现，不受应用显示设置和插件状态影响。
- 五个内置应用均支持排序；智能心跳、魔法笔记和本机推理监控可独立设置启用与常驻，知识库始终显示，设备共享在测试阶段默认关闭，可启用但不常驻侧栏。未常驻的已启用应用仍可从应用菜单打开。
- 为插件应用和插件工具保留明确的入口契约，不提前建设插件安装能力。

## 4. 非目标

- 首期不提供应用商店页面、商店导航、推荐位或安装按钮，也不提供第三方插件搜索、下载、
  安装、更新、签名验证或卸载。内置应用的浏览、搜索与打开属于应用中心，不依赖商店。
- 不把文件树、终端或浏览器重新实现到左侧栏。
- 不改变助手工作栏的面板实例、停靠、执行空间和安全边界。
- 不允许隐藏运行记录、当前对话或设置。
- 不因隐藏可选应用而删除业务数据。
- 不把“显示在侧边栏”解释为停止智能心跳计划或后台任务。
- 不提供任意本机程序启动器。
- 首期资源监控不采集远程主机、GPU、显存或网络吞吐，不提供后台告警和历史持久化。

## 5. 功能要求

### FR-1 入口分类

系统必须为每个可见入口声明稳定类型：`system-entry`、`application` 或 `system-tool`。界面位置、
设置项和点击结果均以该类型为准，不根据当前页面临时改变类型。

### FR-2 固定系统入口

“当前对话”固定在主导航首位；“运行记录”固定在应用区之后；“设置”固定在侧栏底部。
这些入口不出现在应用显隐、工具固定或插件管理设置中。

### FR-3 内置应用区

主导航在当前对话之后按共享保存顺序显示应用，知识库始终显示，可选应用仅显示已启用且常驻项；运行记录位于应用区之后。五个应用均可排序。本机推理监控入口打开独立 Modal，其余应用打开对应一级页面，保留
现有徽标、范围和页面状态。管理 Modal 列出全部内置应用，知识库只提供“打开”和排序。

### FR-4 隐藏应用

取消常驻只移除主导航捷径，不删除数据、不修改启用状态，也不终止正在进行的操作。
关闭可选应用则同步移除业务入口，保留常驻偏好；知识库不受这些偏好影响。心跳关闭后的执行边界见[应用启停与执行](../conversation-supervision/logic-design.md#应用启停与执行)。
配置保存成功后各入口使用同一已确认状态，失败时保持原状态并允许重试。

### FR-5 应用中心入口

侧栏底部提供“应用”（英文 `Apps`）和独立“设置”入口，两个按钮均显示文字。点击“应用”向上展开锚定按钮的轻量菜单，无模态遮罩。菜单列出已启用应用，不按是否打开过、历史记录或常驻状态筛选；点击应用行关闭菜单，本机推理监控打开 Modal，其余应用在主内容区打开页面。
菜单底部“管理应用”关闭菜单并打开既有管理 Modal，在其中浏览、搜索全部内置应用，为已关闭的可选应用提供设置与重新开启入口。无搜索结果时显示空状态并可清除搜索。
首期不展示商店、安装、推荐或系统工具清单。入口具有可访问名称，Escape 关闭后恢复触发位置的焦点。

### FR-6 文件浏览器入口

在右侧选择“工作区”Tab 时聚焦默认存在且不可关闭的单实例。该实例保持
“跟随当前上下文”或“固定到指定对象”状态；迁移或布局修复发现实例缺失时补回，并默认跟随
当前项目。没有项目时使用已配置的默认工作区。跟随上下文所需的路径不可用时，面板显示修复
入口；已有有效固定目标不受当前项目和默认工作区状态影响。固定目标失效时修复该目标，不静默回退到其他目录。

### FR-7 终端入口

选择已有终端 Tab 仅激活该实例，保持目标、会话和历史状态。通过工作栏“+”选择终端时
创建绑定当前执行空间的新实例，不按目标复用已有实例；无项目时使用本机 Home。
远程项目的新实例绑定其托管 SSH 执行空间和权威目录。创建失败保留当前主页面与其他实例。

### FR-8 浏览器入口

选择已有浏览器 Tab 保留其绑定目标、页面和导航状态；通过工作栏“+”选择浏览器时创建新实例，
有活动 Conversation 时绑定该会话，否则创建待绑定空实例。同一 Conversation 的实例共享隔离
登录上下文，页面与导航状态独立。入口不打开系统默认浏览器，也不创建旁路 WebView。

### FR-9 资源监控入口

通过右侧工作栏“+”打开或聚焦单实例的本机“资源监控”，已有面板直接选择其 Tab。面板显示
整机 CPU 使用率、内存使用量与总量、磁盘读写速率，以及 GoodBuddy 桌面进程的 CPU、内存
和进程数摘要。指标不可用时显示具体项目和原因，不能显示为 `0`。

资源面板处于可见活动状态、工作栏已展开且应用窗口未隐藏或最小化时，每 2 秒采样一次，在
Renderer 内存中最多保留最近 5 分钟。任一条件不满足时停止采样；首期不在后台持续监控，
也不据此产生侧栏告警。首次采样及停止后恢复的首次采样只建立 CPU 和磁盘 IO 速率基线，
不显示伪造的 `0` 值。

### FR-10 工作栏入口状态

工具面板已激活时，对应 Tab 显示选中状态；面板存在但未激活时保持普通状态。运行中、错误或
等待用户处理可以显示徽标，但必须有可访问文字，且不得自动抢占当前面板。

### FR-11 应用导航设置

管理 Modal 的五个应用行均提供上下移动和拖动排序，不受启用或常驻状态限制；管理列表、菜单和侧栏共用一份顺序。箭头边界按完整顺序计算，搜索过滤不丢失隐藏项。智能心跳、魔法笔记和本机推理监控另提供应用设置、常驻管理；知识库提供“打开”和排序，不添加通用空设置页或开关。设备共享提供启用设置、打开和排序，不提供常驻。原工作区配置入口及心跳单条计划 enabled 保持不变。设置中“启用应用”与“常驻左侧菜单”分别保存，
修改即时提交；请求期间串行处理并禁用会修改同一配置的控件，失败就地反馈。
魔法笔记设置统一从应用中心对应行进入，笔记页与全局设置不再提供重复入口。持久化成功后的设置变更同步覆盖工具配置写入；每次重开中心先刷新并锁定修改，较新的确认快照优先于迟到的读取结果。

### FR-12 偏好持久化

五个应用的顺序及可选应用启用、常驻按设备持久化，重启后恢复。默认顺序为知识库、智能心跳、魔法笔记、本机推理监控、设备共享。心跳和测试阶段的设备共享默认关闭，其余应用默认启用；心跳和魔法笔记默认常驻，本机推理监控默认不常驻，设备共享不提供常驻开关；
魔法笔记待办数量默认显示，评论方式与形式沿用现有默认值。迁移保留已保存的启用、常驻和排序选择，
旧魔法笔记入口开关绑定业务启用值，迁为“启用应用”并保留原值；常驻使用独立配置，
只有已发布的独立显隐偏好才映射到常驻，不能由常驻推导业务启停。旧可选应用顺序补入知识库、智能心跳默认位置并保留已有相对顺序，具体补齐规则见[技术设计](./technical-design.md#43-持久化与-ipc)。`heartbeatEnabled` 的缺失值与保存值按[应用启停与执行](../conversation-supervision/logic-design.md#应用启停与执行)处理；不读取未发布草案中的 `knowledgeEnabled`。

### FR-13 窄窗口行为

窄窗口下主侧栏仍按现有抽屉方式显示，应用中心和设置保持可操作且不重叠。应用列表可滚动，
搜索、设置及键盘排序不依赖拖拽；工具沿用右侧工作栏响应式规则，不搬到左侧。

### FR-14 项目活动汇总

用户在任一项目中都能查看跨项目的待处理、运行中与已完成未查看会话，并从活动列表直接进入所选会话。
左上角使用一个固定两行的按钮：第一行显示项目名，第二行显示全局活动摘要，无活动时显示“暂无活动”，按钮高度不随活动变化。点击任一行打开同一个锚定工作空间菜单，默认预览当前项目，全部项目范围从菜单内切换；无活动时仍可查看最近会话。
左栏依次提供“全部项目、本地、远程、消息通道”分类，远程能力关闭时隐藏远程分类及其项目；支持跨分类搜索、远程主机折叠及独立项目设置。项目行按名称、活动数量、目录分行显示，无活动时省略数量行，项目顺序不随活动数量变化。
悬停或键盘聚焦项目只预览右栏，点击项目直接进入，优先恢复本次应用会话内上次打开的有效会话，否则选择最近会话；普通项目无会话时创建，消息通道无会话时保持空态。点击右栏会话进入确切会话。
右栏默认依次列待处理、运行中、最近会话，最近会话最多 10 条；已完成未查看在行内标注。“全部、待处理、运行中、已完成”筛选与“新建会话”同排，新建使用预览项目，全部项目范围使用当前项目，消息通道禁用手动新建。左栏底部“新建项目”进入真实项目创建流程。

新建本地项目必须填写名称并选择根目录，空目录或纯空白目录不能创建。此要求仅适用于创建；历史空目录项目仍可编辑和保存，内置默认项目与消息通道项目的初始化规则保持不变。
活动计数、待处理、运行中及已完成筛选不受最近 10 条限制；菜单不继承侧栏会话搜索条件。计数与排除规则见
[活动逻辑](./logic-design.md#9-项目活动汇总)，交互见[活动界面](./ui-design.md#10-项目活动汇总)。

右栏会话显示与侧栏一致的实际更新时间；缺少会话摘要的任务活动不显示时间。菜单从完整入口下方展开，短窗口内缩小高度并保持内部可滚动，入口不被菜单覆盖。

左栏底部“新建项目”旁提供低强调的“已归档”入口，支持搜索和逐项恢复。恢复保留项目数据与原本地／远程分类，不自动进入项目；通道项目及关闭远程能力时的 SSH 项目不提供恢复操作。右下角固定“进入项目”按钮，进入预览项目；全部项目范围使用当前项目，与“新建会话”的目标规则一致。进入仍经过未保存修改检查。

验收覆盖跨项目后台运行、同会话多任务去重、提问与审批优先、较早的仍在运行或等待处理的
会话可见，以及从带搜索条件的页面或有未保存修改的设置页跳转。成功完成后保留“已完成”
通知，直到用户实际查看该会话；从活动菜单或普通侧栏进入均可清除。设置覆盖下的聊天及
隐藏文档不算查看。完成通知仅保留在当前应用会话内，初始任务历史不补发通知，失败和取消
不产生完成通知；普通未读标记本身不构成活动。

## 6. 权限与安全

- 快捷入口不授予新的文件、命令、网络或浏览器权限。
- 系统工具继续使用 Main、Preload、执行空间 Grant 和既有能力范围，不恢复产品工作模式或一般工具审批。
- Renderer 不因新增入口获得任意文件系统、PTY、进程或 Electron API。
- 资源指标由 Main 采集并以有界结构返回；Renderer 不接收进程命令行、环境变量或任意 PID。
- 资源样本只保存在当前 Renderer 内存中，不写入运行记录、SQLite 或遥测服务。
- 插件贡献类型只是界面与导航声明，不能代替权限清单、用户授权和运行隔离。
- 运行记录继续记录由系统工具触发的受审计操作。

## 7. 产品验收

- 主导航能明确区分固定系统入口和可配置内置应用。
- 运行记录在所有应用显隐组合下保持可见并可打开。
- 左下角不再用“本地工作区”与系统架构占据主要空间。
- 应用菜单只列已启用应用，点击行关闭菜单；本机推理监控打开保留底层工作区的 Modal，其余应用进入主内容区。“管理应用”打开可搜索的既有 Modal。五个应用均可排序，知识库始终可用，四个可选应用可管理启用，其中设备共享不提供常驻，首期无商店入口。
- 系统工具仅从右侧 Tab 与“+”访问；选择 Tab 不创建或改绑实例，“+”可显式创建额外浏览器或终端。
- 资源监控以 2 秒间隔更新，保留不超过 150 个样本；面板不活动、工作栏收起或窗口隐藏、
  最小化后停止请求新样本。
- CPU、内存、磁盘 IO 或 GoodBuddy 指标不可用时，页面区分部分可用与整体失败。
- 取消常驻不删除数据、不停止后台计划；关闭应用按统一规则联动业务入口，保存失败时各处保持原状。
- 魔法笔记设置迁移保留已有选择，应用中心与笔记页共用同一配置。
- 键盘、屏幕阅读器、浅色主题、深色主题和窄窗口均可完成相同操作。

## 8. 分期

### 首期

- 侧栏最底部应用中心打开向上锚定的轻量菜单，无模态遮罩；底部“管理应用”进入与设置相同的整窗 Modal 和可搜索应用列表，设置按钮保持独立。
- 应用中心提供魔法笔记、知识库、智能心跳及本轮追加的本机推理监控入口，不要求安装。本机推理监控 Modal 与服务单独实现和验证。
- 五个应用共享排序；支持智能心跳、魔法笔记、本机推理监控常驻主导航及取消常驻，知识库始终显示。设备共享仅从应用菜单和管理 Modal 进入，业务定义见[设备共享](../device-sharing/README.md)。已启用未常驻应用仍可从菜单打开，取消常驻不删除数据或停止后台任务。
- 通用应用设置统一从应用中心对应行进入；应用页面保留实际业务配置，本机推理监控保留“模型与连接设置”。
  魔法笔记优先接入待办数量、AI 评论方式和评论形式，入口显示与常驻控制统一，避免重复开关。
- 文件、终端、浏览器保留在右侧工作栏 Tab，不在左下角复制入口，也不纳入应用中心。
- 原计划的本机资源监控仍作为系统工具交付项，在右侧增加单实例面板；与应用中心分别实现和验证。
- 保持运行记录为固定系统入口。

首期验收需覆盖：无商店入口时可从菜单访问已启用应用，并从管理 Modal 恢复关闭的可选应用；取消常驻后仍可重新打开和配置；
不同设置入口状态一致；常驻排序重启后保留；右侧工具切换不改变当前应用页面。
本节是范围调整，Demo 交互通过不代表正式功能已经实现。

### 补充要求：魔法笔记迁移与入口联动

- 将现有魔法笔记设置迁入应用中心对应行的设置界面，移除笔记页面内的重复入口。
  魔法笔记可常驻主导航；移除原全局设置入口，保留已有配置值和业务数据。
- 魔法笔记相关布尔开关默认全部开启，包括入口显示（常驻）和未完成待办数量显示。
  AI 评论方式、评论形式是单选项，沿用现有默认值，不把“全部开启”解释为同时选中多个模式。
  新默认值适用于未配置状态，迁移时保留用户已明确保存的选择。
- 知识库侧栏入口始终存在且可调整位置；会话知识范围、检索方式、标签及请求行为继续遵守知识库自身规则。心跳入口按启用和常驻显示，单条计划 enabled 仍由心跳页面管理。
- 可选应用“取消常驻”只移除主导航捷径；“关闭应用”移除该应用在业务界面的入口。
  应用中心保留管理和重新开启入口，重新开启沿用常驻偏好，不自动导航。
- 入口变化不删除已有数据。关闭后已打开的可选应用页显示不可用状态及恢复设置入口。
  已发出的请求和后台任务沿用各功能的生命周期规则，关闭入口不新增强制取消或重放行为。

补充验收：关闭全部可选应用后，知识库侧栏入口仍可用，知识会话入口及心跳单条计划状态不变；管理 Modal 的知识库行提供“打开”和排序，不能启停或取消常驻。心跳执行边界按[应用启停与执行](../conversation-supervision/logic-design.md#应用启停与执行)验收。验证魔法笔记未配置时的默认开启，以及
已有关闭选择在迁移后保留。设置保存失败时各入口保持原状态，不能出现互相矛盾的显示。

### 后续：应用商店与扩展

- 单独设计应用商店的目录、搜索、推荐、详情及安装管理，时间与具体范围另行确定。
- 插件应用和插件工具注册，以及安装、更新、卸载与权限说明。
- 插件应用可常驻主导航；插件工具按工作栏扩展设计接入，不恢复左下角重复系统工具条。
- 用户级快捷键与命令面板接入同一贡献命令。

现有 Demo 的商店页、项目管理和阅读空间安装流程仅保留为未来交互参考，不纳入首期验收，
也不作为已有商店能力的说明。首期实现不预建插件安装服务或远程目录协议。

### FR-15 私有化市场与 YAML 交换（后续）

市场面向组织私有化部署。用户配置市场 URL 后即可获取该来源的应用目录与详情，并按需获取
应用；需要认证的来源复用其登录流程。市场不可达时说明原因并允许重试，不影响已安装应用
和内置应用使用，也不自动切换到公共市场。市场 URL 只影响应用市场，不改变模型、桌面更新
或 Runtime 的下载源。市场 URL 按设备保存，重启后保留；认证失效时提示重新认证。

应用支持以 `.yml` 导入、导出，兼容 `.yaml` 扩展名，用于组织内部共享、备份和迁移。
导出内容为应用定义及可迁移配置，包含格式版本、应用标识、应用版本、入口声明和依赖说明；
凭据、会话、笔记及知识库业务数据不随应用定义导出。导入前展示应用摘要、缺失依赖和与已有
应用的冲突；同标识应用由用户选择更新或取消，不静默覆盖本机配置。成功后展示实际版本与可用状态；
获取、校验或更新失败保留原已安装版本与配置，并显示可重试原因。

YAML 描述文件不能代替模型权重或插件程序包。有外部依赖时应明确资源引用；离线导入仅在
所需资源已具备时可完成使用，否则列出需要补充的资源，不显示为可运行。导入应用不会自动
启动模型或执行任务。

未来 ShareServer 提供私有市场目录、应用定义的导入导出、发布和版本资源分发；桌面端负责
配置来源、获取目录、本地导入导出及应用安装管理。服务端职责归属见
[ShareServer 总体设计](../../architecture/share-network-architecture.md)。本节记录后续需求，
尚未确定 API、YAML Schema 或服务端交付版本，不纳入应用中心首期。

### FR-16 本机模型管理入口（新增计划项）

应用中心提供“本机推理监控”内置管理应用，可选择常驻左侧。从常驻入口、应用菜单或管理 Modal 的“打开”均进入同一独立管理 Modal；来源菜单或管理 Modal 关闭，底层工作区、当前项目、会话及草稿保持不变。该入口统一
查看本机语音识别、OCR、向量生成等服务的运行状态与可用资源指标。

Modal 只有服务列表，显示名称、简短状态、引擎、模型、资源和错误，不显示任务历史、任务页签、单任务取消或外部连接列表。独立向量进程显示 CPU 与工作集内存，并标明进程范围；CPU 预热、采样失败和共享进程 worker 无法独立统计时说明原因，不能用零或整个应用进程占用代替服务指标。活动请求可能仍在排队或加载，不能据此宣称服务正在运行。ASR 当前仅显示按需运行且状态未知；OCR 和向量服务使用各自执行模块的状态。

服务行保留实际支持的启动、停止、重启或模型加载、释放，工具栏保留刷新和模型设置入口。停止后重新启动不自动重放已中断任务。

停止、重启或释放前，在管理 Modal 上方打开紧凑影响确认，展示正在使用该服务的任务和影响；没有已登记活动任务时也说明执行前会再次核对。取消时保留运行状态，
失败时关闭旧确认、显示原因并刷新状态，再次操作须重新确认当前影响。多个应用共用同一模型服务时只展示同一个服务，不重复
启动进程。隐藏管理入口、关闭管理 Modal 或取消应用常驻均不停止模型；卸载模型文件是独立操作。
确认打开时不能关闭底层管理 Modal；Escape 只关闭最上层，提交期间禁止关闭及重复执行。关闭后恢复可用入口焦点，具体规则见 [UI 设计](./ui-design.md#91-本机推理管理)。

资源监控仍是只读系统工具，本机推理监控聚焦本地服务状态。该项独立于商店接入生产源码，支持 OCR 空闲加载与释放、内置向量进程启动／停止／重启；TTS 显示不可用。后端保留请求登记及原有取消能力，供执行路径和服务影响校验使用。各引擎边界见
[技术清单](./technical-design.md#111-本机推理任务与执行服务)，验证范围见[实施进度](./progress.md)。
原首期资源监控的 GoodBuddy 桌面进程统计范围不因此扩大。

### FR-17 主机管理与云环境管理（待实现）

2026-09-28 确认新增两个同级应用：“主机管理”和“云环境管理”。主机管理从设置中心迁入，
两个应用均从应用菜单、管理应用和常驻入口打开主内容区独立页面，不嵌入管理 Modal。
应用中心负责通用应用配置，业务操作在各自页面完成。

导航扩展须保留已有应用排序、常驻偏好和远程能力启用值；取消主机常驻不影响云环境使用
主机能力。两个应用的能力依赖、迁移范围及产品验收由
[主机与云环境 PRD](../remote-host/prd.md)和[功能逻辑](../remote-host/logic-design.md)定义，
业务页面布局见[界面设计](../remote-host/ui-design.md)。该项尚未实现，不改变上文五应用的当前状态描述。