root/goodbuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a0456f687a9525d5dfc0e4f9e1627c1cf49406af
goodbuddy/docs/features/application-tool-navigation/logic-design.md
T
mesalogo 3b560c9a5e feat: add external knowledge retrieval and cross-project activity 
Connect Dify, FastGPT and RAGFlow through read-only bindings, encrypted local credentials, shared retrieval and persistent citations. Configuration and removal affect GoodBuddy only.

Show active conversations across projects, retain older live work, and improve project dialog scrolling. Queue concurrent questions and route managed SSH OpenCode questions through the Agent. Preserve recoverable read/search errors and partial search results.

Document the Electron UI automation standard, real model and external knowledge validation, and remaining acceptance limits.

Validation: earlier full regression passed 4081 tests with 66 skipped; subsequent focused remote-question checks and real Linux evidence are recorded in feature progress. Precommit typecheck and lint passed; latest project dialog and shared UI suites passed 58 tests. The full suite was not rerun for the final dialog changes.

Release note: Use external knowledge in conversations, find active work across projects, and answer concurrent local or managed SSH OpenCode questions. Managed SSH questions require the updated Agent adapter.
2026-09-13 13:10:01 +08:00

8.4 KiB
Raw Blame History

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

文档信息

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

1. 不变量

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

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

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

9. 项目活动汇总

对应 FR-14，按 Conversation ID 聚合，每条会话最多一行。 数据来源为活动会话 ID、会话中的流式消息及待回答/待审批请求，以及全部可见的运行中或 等待处理 Task；不能只取当前项目、当前搜索结果或每条会话的最新 Task。

优先级（高到低） 条件 汇总类别
待回答 消息有待回答问题 待处理
待审批 消息有待审批请求 待处理
Task 等待处理 Task 为 waiting_approval，尚无更具体的消息状态 待处理
运行中 活动会话 ID、streaming 消息或运行中 Task 运行中

同一会话只采用最高优先级状态；Task 的 waiting_approval 也可能对应提问，不能直接 标成待审批。“待处理”和“运行中”数量互斥，全局总数为两者之和；项目计数使用相同结果。 项目归属优先取会话元数据，缺少会话时取 Task 元数据；无项目归属的活动只计入全局汇总。

历史排队项、仅待调度的 Task、终态 Task 和未读标记本身不构成活动。活动结束且没有其他 运行或等待条件时移除该行，不能因历史任务或未读状态继续计数。

Reference in New Issue View Git Blame Copy Permalink