19 KiB
应用导航与系统工具入口功能逻辑设计
文档信息
| 项目 | 内容 |
|---|---|
| 状态 | 应用中心与本机推理监控已接入源码，整体验收待完成 |
| 版本 | 0.4 |
| 日期 | 2026-09-17 |
| 关联 PRD | 应用导航与系统工具入口 PRD |
| 关联 User Stories | User Stories |
1. 不变量
- “当前对话”“运行记录”和“设置”始终是系统入口。
- 运行记录不进入工具注册表、应用显隐设置或插件市场。
- 文件浏览器、终端、浏览器和资源监控始终是系统工具，不能卸载或被插件替换。
- 左下角提供应用中心和独立固定设置入口；文件、终端、浏览器、资源监控只通过右侧工作栏 Tab 和“+”访问，不进入应用中心。
- 四个内置应用共享保存顺序。知识库和智能心跳始终启用并常驻，位置可调整；魔法笔记、本机推理监控可独立设置启用和常驻。取消常驻不关闭功能，关闭不删除数据或导航偏好。
- 入口不能扩大执行空间、文件、PTY、网络或浏览器权限。
- 应用中心始终可达，点击向上展开无模态遮罩的锚定菜单，只列已启用应用，不使用打开历史或常驻过滤。菜单底部“管理应用”打开既有 Modal，关闭的可选应用在其中仍可搜索、配置和重新开启。
- 所有入口和新请求的功能判断读取同一份保存成功的权威设置；保存中的目标值不提前生效。
2. 入口模型
type NavigationContribution =
| {
type: 'system-entry'
id: 'chat' | 'activity' | 'application-center' | 'settings'
placement: 'primary-start' | 'primary-end' | 'footer'
}
| {
type: 'application'
id: 'knowledge' | 'heartbeat'
source: 'builtin'
alwaysShown: true
}
| {
type: 'application'
id: 'magic-notes' | 'local-inference'
source: 'builtin'
enabled: boolean
pinned: boolean
}
| {
type: 'system-tool'
id: 'workspace' | 'terminal' | 'browser' | 'resources'
workbarAppId: 'workspace' | 'terminal' | 'browser' | 'resources'
}
该模型是首期的逻辑投影，启用值来自各应用的唯一业务配置，常驻及顺序来自导航偏好。 应用清单为魔法笔记、知识库、智能心跳、本机推理监控，打开无需安装。市场不加入本轮清单。
3. 主导航组合规则
主导航按以下顺序计算：
当前对话
应用（按保存顺序；知识库和智能心跳始终显示，可选应用仅显示启用且常驻项）
运行记录
当前对话、运行记录和设置不参与应用排序。默认应用顺序为知识库、智能心跳、魔法笔记、本机推理监控；魔法笔记默认常驻，本机推理监控默认不常驻。过滤可选项不留下空白。 常驻、取消常驻和排序按设备保存，重启后恢复。排序只发生在应用区，不移动固定系统入口。 管理卡片、应用菜单和主导航共用完整应用顺序，分别按搜索、启用、启用且常驻过滤；过滤不删除顺序记录，重新开启或常驻时按保存顺序恢复。 每张管理卡片均可排序，包括关闭或未常驻的应用。上下移动以完整保存顺序中的相邻应用为目标，拖动使用同一移动规则。搜索时禁用拖动，箭头仍按完整顺序移动，保留未命中应用及其相对顺序。
3.1 应用可见性与业务状态
下表仅适用于可选应用。知识库和智能心跳始终可用，管理 Modal 中提供“打开”和排序，保留原工作区实际配置，不增加启用、常驻开关或通用空设置页。心跳单条计划 enabled 仍按原业务规则控制计划。
| 常驻偏好 | 功能启用 | 结果 |
|---|---|---|
| 是 | 是 | 主导航显示，可从主导航或应用中心打开 |
| 否 | 是 | 主导航隐藏，仍可从应用中心打开，后台和数据保持原状 |
| 是 | 否 | 主导航、应用菜单和业务入口隐藏，管理 Modal 保留设置，记住常驻及顺序 |
| 否 | 否 | 主导航、应用菜单和业务入口隐藏，管理 Modal 保留设置，记住未常驻状态 |
管理 Modal 浏览和搜索包含关闭的可选应用，搜索不修改启用或常驻。轻量菜单仅显示已启用项，点击行先关闭菜单；本机推理监控打开独立 Modal，其余应用请求主内容区导航。管理 Modal 的“打开”和常驻入口遵守同一规则。打开已启用应用不自动常驻； 取消当前应用的常驻不关闭当前页面或本机推理监控 Modal。关闭应用后不能从旧入口继续执行新的业务操作。 停用时仍允许管理常驻偏好，界面说明重新开启后才会显示入口。
3.2 关闭应用与恢复
关闭与恢复仅适用于可选应用，知识库页面、会话控件及关联，以及智能心跳入口、页面和计划 enabled 不受可选应用偏好影响。
| 对象 | 关闭后的结果 | 重新开启后的结果 |
|---|---|---|
| 当前已打开应用页或本机推理监控 Modal | 原位置显示“应用已关闭”的不可用状态；保留内容状态及草稿，不强制跳转。重新启用从应用中心卡片设置进入，监控 Modal 需先关闭 | 恢复可用性；仍打开时恢复内容，已关闭或离开则不自动打开 |
| 已在执行的请求及后台操作 | 沿用功能自身的取消、完成和清理生命周期；本次应用开关不新增取消策略 | 不自动恢复、中断后重跑或补发任务 |
| 数据、常驻及顺序 | 保留原值，业务入口按启用状态过滤 | 按保存的常驻及顺序恢复入口，不把未常驻应用自动常驻 |
知识请求及单个知识库实例停用、配置修改或删除继续遵守知识库自身规则，没有应用级禁用判断。
3.3 魔法笔记设置迁移
魔法笔记设置迁入应用中心卡片的设置页；笔记页面和全局设置均不提供重复入口， 编辑同一配置。启用、常驻、显示未完成待办数量分别控制功能、导航和徽标，不保留重复的 “显示魔法笔记入口”开关。
未配置的应用启用及魔法笔记相关布尔项默认开启；魔法笔记默认常驻，本机推理监控默认不常驻，仍可从应用菜单及管理 Modal 打开。已有保存的 true 和 false 均保留。
AI 评论方式和评论形式继续为单选，沿用现有默认值“即时”和“长评 + 要点”，不能解释为
全部模式同时启用。迁移保留既有单选值及业务数据。关闭数量显示只隐藏徽标，不修改待办。
4. 系统工具打开规则
4.1 通用流程
用户展开右侧工作栏
-> 选择已有 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 资源采样状态
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 |
| 后续私有市场与 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。实现与验证的剩余范围见实施进度。
8. 后续产品决策
后续市场 URL、YAML 交换、ShareServer 目录与分发、插件注册及安装不进入首期。其协议、 扩展身份与安装生命周期由市场功能另行确定；内置应用常驻及排序不依赖这些决策。
8.1 本机推理管理
FR-16 独立于市场排期，作为可常驻的管理 Modal。所有打开入口只改变 Modal 打开状态，不改变底层工作区、项目、会话或草稿；关闭时卸载 Modal，服务生命周期独立。US-F3 只有服务列表，展示名称、状态、引擎、模型及错误。共享服务只展示一次；资源按独立服务进程归属，CPU 预热与指标不可用分别给出原因，不填 0，不将宿主进程占用分摊给共享线程。采样与单位见技术设计。ASR 没有 Worker 就绪观测，显示按需运行且状态未知；活动请求不覆盖服务状态。OCR 状态来自 Renderer Worker，向量状态来自 Broker。
US-F4 的 Modal 单任务取消入口已移除。后端取消行为保留：Worker 确认或退出前仍计入活动任务和停止影响，即使调用方已收到取消或超时错误；任务先完成则保留真实完成结果，不通过终止共享服务模拟单任务取消。
| 服务管理方式 | 可提供操作 | 结果要求（US-F5） |
|---|---|---|
| GoodBuddy 受管子进程 | 引擎已支持的启动、停止、重启 | 共用同一服务实例；操作成功由真实进程和服务就绪状态确认 |
| 外部服务 | 在模型与连接设置中管理 | 不列入本机服务，不推断本机归属 |
| 进程内模型 | 引擎实际支持的加载、释放 | 不显示虚构 PID 或进程启动、停止状态 |
停止、重启或释放均先打开紧凑的嵌套影响确认，列出任务和影响；无已登记活动任务时说明执行前再次核对。取消确认不改变运行状态。 确认存在时禁止关闭底层管理 Modal；提交期间两层均不能关闭，重复操作被拒绝。未提交时 Escape 只关闭确认，确认关闭后才可用 Escape 关闭管理 Modal。焦点规则由 UI 设计定义。 实际操作失败关闭旧确认、显示错误并刷新快照；刷新期间或失败时禁用服务操作。再次操作重新取得当前任务清单并要求确认，避免重复提交旧清单。 再次启动不重放已中断任务；关闭管理 Modal、关闭管理应用或取消常驻不停止服务，卸载模型文件为独立操作。 当前向量服务允许确认影响后停止，并拒绝确认清单未包含的新任务；OCR 仅空闲时允许释放。 ASR 按请求加载与释放，支持独立取消；TTS 尚无执行服务。具体适配边界以 技术清单为准。活动请求仅在影响确认中展示，主列表不展示历史。应用退出清理沿用各引擎原有路径。
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、通道的稳定项目顺序；缺少项目 元数据的归属组及“未归属项目”组放在已知项目之后。无归属组只用于访问这些会话，不增加 项目计数。每个项目内依次列待处理、运行中、已完成会话，同类别保留来源顺序。
展开项目只改变菜单层级，不导航。选中项目的活动行全部移除后返回项目列表；全局无活动行后 关闭菜单并隐藏摘要入口。后台更新保留仍存在的焦点项，删除焦点项时将焦点 移至当前层可用项。关闭菜单后，新的活动只恢复摘要，不会自动重新打开菜单。