root/goodbuddy

Fork 0

Files

T

lofyer de497b9553 docs: expand product planning

2026-08-14 13:24:42 +08:00

38 KiB

Raw Blame History

GoodBuddy 跨平台 AI 桌面助手功能方案设计

1. 文档信息

项目	内容
文档类型	产品设计基线
状态	初始方案
版本	0.1
日期	2026-07-29
适用产品	GoodBuddy
产品形态	常驻型跨平台 AI 桌面助手
目标平台	Windows、macOS、Linux（含统信 UOS、银河麒麟）
目标架构	x86_64、ARM64（含鲲鹏、飞腾）
推荐技术栈	Electron + React + TypeScript + Vite
可选扩展	Rust Sidecar，用于本地索引、OCR、文档解析等性能敏感任务

本文定义产品范围、功能模块、关键交互、权限安全、跨平台策略、非功能指标、版本路线及验收要求。产品参考通用 AI 桌面助手形态，不依赖任何第三方产品的私有实现。

2. 产品定位

2.1 产品愿景

打造一款随时可唤起、能够理解用户显式提供的桌面上下文、可以安全调用工具的 AI 助手。用户无需频繁切换应用，即可完成问答、写作、翻译、总结、截图分析、文件问答、知识检索和轻量任务自动化。

2.2 核心价值

随时可用：通过全局快捷键、系统托盘或悬浮助手快速唤起。
理解当前工作：在用户明确授权后读取选中文本、截图、剪贴板和文件。
回答有依据：知识库回答提供文件、页码或段落引用。
执行可控制：工具调用必须经过权限校验、参数校验和必要的用户确认。
跨平台可交付：在 Windows、macOS、Linux x64/ARM64 上保持核心任务一致。
企业可治理：支持模型、网络、权限、数据和更新策略的集中管控。

2.3 目标用户

用户类型	典型需求
知识工作者	写作、翻译、总结、资料整理、文件问答
研发人员	代码解释、日志分析、技术资料检索、生成代码草稿
企业员工	查询内部知识、调用企业技能、生成业务内容
IT 管理员	批量部署、模型配置、权限控制、审计和版本治理
国产化环境用户	在统信 UOS、银河麒麟、鲲鹏、飞腾设备上稳定运行

2.4 产品原则

默认最小权限，不在首次启动时集中申请全部系统权限。
默认只处理用户主动输入或显式添加的上下文。
任何即将发送给模型的上下文都必须可见、可预览、可移除。
模型输出不等同于执行授权，工具权限由独立权限层判定。
核心体验保持一致，受系统限制的能力采用渐进增强和明确降级。
安全、权限、更新签名和数据生命周期属于基础能力，不延期补做。

2.5 当前非目标

不替代浏览器、IDE、办公软件或操作系统 Shell。
MVP 不提供任意 Shell、任意代码执行和无人值守高风险操作。
不持续录屏、持续监听输入或默认保存完整剪贴板历史。
不默认上传桌面内容、全部文件或用户未选择的数据。
暂不支持龙芯 LoongArch、申威 Sunway 等架构。
MVP 不建设开放插件市场、跨设备同步和完整企业设备管理平台。

3. 版本范围

3.1 优先级定义

优先级	定义
P0 / MVP	首个正式版本必须具备，构成核心使用闭环
P1	MVP 后优先建设，提升效率、知识能力和企业可用性
P2	平台稳定后建设，涉及生态、复杂代理或更高系统权限

3.2 MVP 核心闭环

安装并完成模型配置
→ 使用快捷键唤起
→ 输入问题或添加文本、截图、剪贴板、文件
→ 查看本次将发送的上下文
→ 获得流式回答和来源引用
→ 复制结果或确认执行低风险工具
→ 在历史记录中继续对话

3.3 版本能力概览

MVP

主窗口、快捷面板、系统托盘、全局快捷键。
可关闭的悬浮助手。
多轮 AI 对话、流式输出、停止、重试和历史记录。
用户主动添加的截图、剪贴板、选中文本和文件上下文。
单个本地知识库、向量检索和来源引用。
白名单内置工具及逐次授权。
基础通知、设置、权限中心、诊断日志和更新检查。
Windows、macOS、Linux x64/ARM64 安装包与兼容性验证。

P1

多知识库、文件夹同步、增量索引、OCR、混合检索和重排。
企业私有模型、代理网络、企业技能目录和签名策略。
多步骤任务、人工检查点、失败重试和任务历史。
更新灰度、回滚、企业更新源和审计导出。
更完善的活动窗口、选中文本及上下文白名单能力。

P2

定时低风险自动化和多步骤智能代理。
插件 SDK、技能市场和团队知识库。
SSO、SCIM、集中设备管理和跨设备会话同步。
离线本地模型及云端、本地混合推理。

4. 产品信息架构

4.1 产品入口

入口	主要功能
系统托盘/菜单栏	打开助手、新建对话、暂停上下文能力、设置、退出
全局快捷键	唤起或收起快捷面板
悬浮助手	查看状态、打开快捷面板、进入常用动作
主窗口	管理对话、知识库、技能、任务、通知和设置
系统通知	跳转到已完成、失败或待确认的任务
深度链接	在可信来源下打开指定会话或功能页面

4.2 主窗口导航

主窗口
├── 对话
│   ├── 会话列表
│   ├── 消息区域
│   ├── 上下文附件
│   └── 输入与快捷动作
├── 知识库
│   ├── 知识库列表
│   ├── 文档与索引状态
│   └── 检索测试
├── 技能与任务
│   ├── 可用技能
│   ├── 权限范围
│   └── 任务历史
├── 通知中心
└── 设置
    ├── 通用与外观
    ├── 模型服务
    ├── 快捷键与悬浮助手
    ├── 权限与隐私
    ├── 存储与知识库
    ├── 网络与代理
    ├── 通知与更新
    └── 诊断与关于

4.3 核心状态

未配置：没有可用模型，引导用户完成配置或登录。
空闲：等待输入。
生成中：模型正在流式输出，可停止。
工具待确认：等待用户检查参数并授权。
任务执行中：展示当前步骤、进度和取消入口。
离线：允许查看本地历史和知识库状态，禁用网络模型调用。
权限受限：展示缺失权限和降级方案。
需要更新：显示可用版本，不强制中断当前任务。

5. 详细功能设计

5.1 首次启动与初始化

用户目标

用户能够了解产品能力、完成模型配置、按需启用快捷键，并在不被强制索取权限的情况下开始第一次对话。

功能项

服务条款、隐私说明和数据处理方式确认。
选择个人模式或企业模式。
登录企业账号，或配置兼容的模型 API。
检测网络、代理和模型连接。
设置默认快捷键及冲突检测。
可选设置开机启动和悬浮助手。
权限按首次使用能力时申请，不在向导内强制一次性申请。
提供示例问题和快速功能介绍。

异常与降级

模型连接失败时保留配置并展示可诊断的错误原因。
系统安全存储不可用时禁止静默保存明文密钥。
快捷键冲突时建议其他组合，并允许跳过。
企业策略未拉取成功时，只使用最近一次有效且签名正确的策略。

MVP 验收

新用户在三分钟内能够完成配置并发出第一条消息。
跳过非必要设置不影响基础对话。
连接测试不会在日志中输出 API Key。

5.2 快捷唤起与快捷面板

用户场景

用户在任意应用中工作时，通过快捷键快速提问或处理当前内容，无需切换到完整主窗口。

功能项

全局快捷键注册、修改和冲突检测。
快捷面板显示、隐藏、失焦自动收起。
再次按快捷键切换显示状态。
Esc 收起，Enter 发送，组合键换行。
快速动作：总结、翻译、润色、解释、截图问答、文件问答。
当前会话继续或新建临时会话。
根据鼠标位置或活动显示器选择展示屏幕。
可展开为主窗口，并保留输入和上下文。

边界条件

快捷键被系统或其他软件占用。
Wayland 不允许直接注册全局快捷键。
多显示器缩放比例不同或显示器在运行中断开。
全屏应用、安全桌面、锁屏界面不允许覆盖。
输入法组合状态下不能误触发送。

降级策略

快捷键注册失败时使用托盘入口。
Wayland 优先使用 Global Shortcuts Portal，不可用时提示用户在桌面环境中配置启动命令。
任意定位受限时显示普通居中窗口，不阻断核心功能。

MVP 验收

热唤起本地 UI 的 P95 不超过 300ms。
快捷键冲突有明确提示且不覆盖已有注册。
多显示器切换后窗口始终处于可见区域。
展开主窗口后输入、附件和生成状态不丢失。

5.3 系统托盘与应用生命周期

功能项

打开/隐藏主窗口。
新建对话。
显示当前运行状态。
暂停上下文采集能力。
开启/关闭悬浮助手。
检查更新、设置、退出。
单实例运行，第二次启动时激活已有实例。
用户关闭主窗口时按设置退出或最小化到托盘。
系统启动后按用户选择自动运行。

边界条件

Linux 桌面环境没有托盘服务。
应用更新、系统关机或崩溃时存在未完成任务。
第二实例携带深度链接或文件参数。

MVP 验收

无托盘环境仍能通过应用菜单和主窗口完成全部核心操作。
退出前停止网络流、结束任务并清理临时截图。
单实例参数经过校验后再交给已有实例。

5.4 悬浮助手

功能项

悬浮球或迷你条显示。
单击打开快捷面板，右键打开快捷菜单。
拖动、贴边、隐藏和恢复。
状态展示：空闲、生成中、任务中、错误、未读。
置顶、透明度和全屏自动隐藏设置。
用户可完全关闭悬浮助手。

边界条件

Wayland 禁止任意窗口定位。
macOS 多空间、全屏窗口和多屏切换。
Linux 窗口管理器忽略置顶或透明区域点击穿透。
DPI 变化导致保存坐标越界。

MVP 验收

重启后恢复到当前可见屏幕范围。
透明区域不拦截其他应用的鼠标事件。
不支持悬浮定位时自动降级为普通迷你窗口或托盘入口。

5.5 AI 对话

功能项

新建、重命名、置顶、搜索、删除会话。
多轮上下文和会话级模型选择。
流式输出、停止生成、重新生成、编辑后重发。
Markdown、表格、代码块、公式和引用渲染。
代码复制、消息复制、反馈和导出。
会话标题自动生成，允许手动修改。
消息附件、工具调用步骤和来源引用。
上下文窗口及预计使用量提示。
网络失败后的重试和续接策略。

关键交互

用户发送后立即创建用户消息和助手占位消息。
首段内容到达后进行增量渲染。
工具调用显示为独立步骤卡片，不与普通文本混合隐藏。
用户停止后立即中断网络请求和后续工具步骤。
引用标记可打开原始文件、页码或文本片段。

异常与边界

模型超时、限流、拒答或返回格式异常。
流式连接中断，仅收到部分内容。
上下文超过模型限制。
用户重复发送、快速切换模型或删除生成中的会话。
超长消息导致渲染性能下降。

MVP 验收

用户停止后不再产生模型费用或工具调用。
网络中断时保留已生成内容并提供重试。
上下文超限时明确展示裁剪或摘要策略。
长会话采用虚拟列表或分段渲染，不持续阻塞 UI。

5.6 上下文采集与上下文胶囊

上下文来源

用户输入文本。
用户主动添加的选中文本。
单次读取的剪贴板文本、图片或文件路径。
区域截图或窗口截图。
用户选择或拖入的文件。
用户选择的知识库。
P1：经授权的活动应用名称、窗口标题和页面片段。

交互规则

每个上下文显示为独立胶囊或附件卡片。
卡片展示类型、来源、大小、解析状态和数据去向。
用户发送前可以预览、删除或替换。
移除后，请求体和临时缓存不得继续包含对应数据。
高敏感内容在发送前提示风险。
会话授权不得自动升级为永久授权。

上下文等级

等级	行为
无上下文	只发送用户输入
显式上下文	用户逐项触发采集，作为 MVP 默认方式
会话授权	当前会话可使用指定来源，关闭会话后失效
持续上下文	P2 可选能力，默认关闭并持续显示采集指示

禁止行为

不读取密码框和安全输入区域。
不在后台静默采集未授权窗口内容。
不因模型请求而自动扩大文件或目录访问范围。
不将应用名称、窗口标题默认视为非敏感信息。

5.7 截图与 OCR

功能项

全屏、区域、窗口截图。
多显示器和高 DPI 支持。
截图前自动隐藏助手窗口。
截图预览、重截、删除、标注和打码。
P1：本地 OCR、版面识别和文本复制。
系统权限状态检测和设置入口。

平台策略

Windows 使用系统屏幕捕获能力，避开 UAC 安全桌面。
macOS 按需申请屏幕录制权限。
X11 使用可验证的截图能力。
Wayland 优先使用 Screenshot/ScreenCast Portal 和 PipeWire。

MVP 验收

截图结果不包含自动隐藏的助手窗口。
多屏负坐标、不同缩放比例下选区与输出一致。
用户取消时不生成可持久化附件。
权限拒绝时提供文字输入、文件上传等替代方式。
临时截图在会话结束、清理或退出时按策略删除。

5.8 剪贴板

功能项

正常粘贴。
用户点击“从剪贴板添加”后单次读取。
识别文本、图片和文件路径。
显示预览、格式、大小和移除操作。
敏感模式下完全禁用读取。

边界条件

剪贴板为空、格式不支持或内容过大。
密码管理器生成的临时内容。
Linux 主选择区与常规剪贴板差异。
远程桌面共享剪贴板。

MVP 验收

未触发添加动作时不保存剪贴板内容。
读取操作不修改或清空系统剪贴板。
超过限制时不上传，并展示清晰原因。

5.9 文件处理

MVP 支持格式

文本：TXT、Markdown、JSON、CSV。
文档：PDF。
图片：PNG、JPEG、WebP。
常见源代码和配置文件。

P1 支持格式

DOCX、PPTX、XLSX。
文件夹和批量文件。
扫描 PDF OCR。

功能项

文件选择、拖放和最近文件。
类型、大小、数量和访问权限校验。
文本解析、页码或段落定位。
解析进度、取消、重试和失败原因。
只发送用户问题需要的片段，而非默认上传完整文件。
文件发生变化后标记缓存或索引过期。

安全要求

不执行附件中的脚本、宏或嵌入对象。
防止压缩炸弹、路径穿越和符号链接越权。
解析进程配置 CPU、内存、时间和输出大小限制。
网络盘离线或文件无权限时不得无限重试。

MVP 验收

文件解析不阻塞 Renderer 主线程。
解析失败可重试或移除，且不破坏当前会话。
引用能够定位到文件、页码或段落。

5.10 本地知识库

用户场景

用户导入常用资料，并在后续对话中获得基于资料、带原文引用的回答。

MVP 功能

创建一个本地知识库。
导入、删除和重新索引文件。
展示解析、切块、嵌入、完成和失败状态。
在对话中启用或停用知识库。
向量检索和来源引用。
查看引用原文。
展示存储占用并支持完整清除。

P1 功能

多知识库。
文件夹同步和增量索引。
关键词与向量混合检索。
重排、OCR、重复文件识别。
企业知识库及权限继承。

边界条件

嵌入模型变化导致向量不兼容。
文件更新、重复导入、磁盘空间不足。
中文分块效果、扫描 PDF 和复杂表格。
ARM64 原生向量依赖没有稳定构建。

MVP 验收

每个检索片段包含文件、页码/章节和文本偏移元数据。
删除知识库时联动删除正文缓存、向量和元数据。
索引失败可以重试且不破坏已有可用索引。
回答中的引用可以打开并展示对应原文。

5.11 模型服务

支持方式

OpenAI 兼容 API。
企业私有模型服务。
后续接入特定云模型厂商。
P2 接入本地模型。

模型网关职责

统一流式请求、停止、超时、重试和错误格式。
描述模型的文本、视觉、工具调用和上下文能力。
Token 预算与上下文裁剪。
模型路由、降级和可用性检测。
凭据注入，不向 Renderer 暴露密钥。
企业域名白名单、TLS 和代理策略。
统计用量，但默认不记录完整提示词和回答正文。

配置项

服务地址、模型名称、API Key。
默认模型及视觉模型。
超时、重试、代理和自定义请求头。
企业模式下由策略锁定的模型列表。

MVP 验收

保存配置前完成连接测试。
API Key 使用平台安全存储。
模型不支持图片或工具时，在发送前给出提示。
请求取消能够传递到网络层和工具调度层。

5.12 技能与工具调用

MVP 内置工具

纯文本转换：总结、翻译、润色、结构化。
读取用户明确选择的文件。
打开经过校验的网页链接。
在用户选择的位置生成文件草稿。
查询本地知识库。

工具风险分级

等级	示例	默认策略
R0 纯计算	文本格式化、计算、编码转换	可自动执行
R1 本地只读	读取用户本次选择的文件	首次或会话授权
R2 外部只读	网络搜索、查询企业系统	展示数据去向，可按策略授权
R3 可逆写入	创建草稿、生成新文件	执行前确认
R4 外部副作用	发送消息、提交工单、修改远程数据	每次确认并展示完整参数
R5 高风险	Shell、提权、删除、支付	MVP 禁止

调用流程

模型建议调用
→ 检查工具是否注册
→ JSON Schema 参数校验
→ 风险等级判定
→ 用户权限和企业策略判定
→ 必要时展示确认卡片
→ 执行并支持取消
→ 限制和过滤工具输出
→ 将结果返回模型
→ 写入脱敏审计记录

安全要求

模型文本不能绕过权限层直接执行。
工具输出视为不可信数据，不能自动提升为系统指令。
文件路径必须规范化并限制在授权范围。
URL 只允许 https 等白名单协议，并按策略校验域名。
不拼接 Shell 命令，Sidecar 使用结构化参数。

MVP 验收

所有参数通过 Schema 校验后才能执行。
R3 及以上工具必须逐次确认。
每次调用记录工具、参数摘要、授权方式、结果和时间。
超时或取消能够终止请求或子进程。

5.13 任务自动化

P1 功能

将多步工具调用保存为任务。
执行前展示步骤计划、输入和权限。
逐步执行、暂停、取消和人工检查点。
失败重试和从安全检查点继续。
任务历史、输出物和失败原因。
常用任务模板。

P2 功能

定时触发。
无人值守的低风险任务。
条件分支和循环。
企业审批流。

安全和一致性要求

有外部副作用的步骤使用幂等键或显示重复执行警告。
应用崩溃后将任务标记为中断，不自动重放副作用步骤。
输出文件存在时要求选择覆盖、重命名或取消。
系统休眠和网络中断后重新确认任务状态。

5.14 通知与任务中心

功能项

系统通知和应用内通知。
生成完成、任务完成、任务失败和等待确认。
未读数量、全部已读和按类别过滤。
勿扰模式及通知级别设置。
点击通知跳转到对应会话或任务。

隐私要求

锁屏通知默认隐藏提示词、文件名和工具参数等敏感内容。
待确认通知只提示存在待办，不显示完整数据。

MVP 验收

系统通知不可用时仍有应用内通知。
同一事件不重复发送。
目标会话已删除时进入通知详情并提示对象不存在。

5.15 设置与权限中心

设置分组

分组	配置内容
通用	开机启动、关闭行为、语言、主题、缩放
模型	服务地址、模型、凭据、超时、连接测试
快捷键	唤起、截图、快捷动作及冲突检测
悬浮助手	启用、位置、置顶、透明度、全屏隐藏
权限与隐私	截图、辅助功能、剪贴板、文件、通知状态
数据与存储	会话保留、缓存、知识库目录、数据清除
网络	系统代理、自定义代理、证书和域名策略
通知	通知类别、锁屏内容、勿扰
更新	更新渠道、自动检查和下载策略
诊断	日志等级、诊断包、版本和系统信息

交互要求

高风险设置显示影响说明。
企业锁定项显示策略来源和锁定原因。
清除数据前列出会删除的数据范围。
配置写入采用原子替换，损坏时可恢复默认配置。

5.16 自动更新

功能项

启动后后台检查和手动检查。
下载进度、暂停、重试和重启安装。
更新说明、稳定/测试/企业渠道。
P1：灰度发布、失败回滚和企业更新源。
企业可禁用客户端自动更新。

平台策略

Windows 支持 NSIS 或 MSIX，安装包和更新包使用 Authenticode 签名。
macOS 使用 Developer ID 签名、公证和 Hardened Runtime。
Linux DEB/RPM 优先遵循系统包管理器；AppImage 使用独立更新策略。
更新元数据和安装包均需验证签名、版本、平台与架构。

MVP 验收

下载或安装失败后旧版本仍可运行。
任务执行中不强制退出。
架构或平台不匹配时拒绝安装。
更新日志不包含下载凭据和敏感请求头。

5.17 企业管理

P1 能力

签名企业策略文件。
模型、域名和技能白名单。
代理、私有证书和私有模型配置。
数据保留、遥测、日志和更新策略。
工具风险上限和授权方式。
审计记录导出。

P2 能力

SSO、SCIM。
集中设备管理。
团队知识库和权限同步。
远程策略控制台。

策略规则

企业策略优先于本地用户配置。
策略必须验签，验签失败时不生效。
离线使用最近一次有效策略，并支持有效期。
策略变更产生审计事件。
UI 和本地配置文件都不能绕过锁定项。

6. 权限与隐私

6.1 权限矩阵

能力	Windows	macOS	X11	Wayland	默认策略
全局快捷键	原生支持	原生支持	通常支持	优先 Portal	开启，失败时降级
屏幕截图	系统能力	需录屏权限	常见接口	Screenshot/ScreenCast Portal	用户主动触发
选中文本	按应用能力降级	可能需辅助功能权限	依应用和无障碍能力	通常受限	默认关闭
剪贴板	支持	支持	Clipboard	受合成器管理	单次触发
文件读取	文件选择器	文件选择器	文件选择器	FileChooser Portal 优先	仅选择范围
通知	系统通知	通知权限	通知服务	Portal/通知服务	首次需要时申请
开机启动	系统启动项	Login Items	XDG Autostart	桌面环境相关	用户开启

6.2 权限申请原则

在首次使用具体能力前解释用途并申请。
提供一次、当前会话、长期允许和拒绝选项。
长期授权可在权限中心撤销。
拒绝权限后不重复打扰，并提供替代路径。
操作系统权限被撤销后立即停止能力并更新 UI 状态。
高风险能力不能通过一次授权永久放行。

6.3 敏感信息保护

本地检测 API Key、访问令牌、密码、身份证号、银行卡号等常见敏感模式。
检测结果只作为风险提示，不宣称完全准确。
企业策略可阻止特定数据发送给外部模型。
日志不记录完整提示词、附件正文、截图、密钥和令牌。
提供隐私模式：不保存会话、不保留附件、不写入知识库。

6.4 数据生命周期

数据	默认策略	用户控制
对话消息	本地保存，企业策略可覆盖	删除单条、会话或全部历史
临时截图	请求或会话结束后清理	立即删除
文件解析缓存	文件仍被引用时保存	单文件或统一清理
知识库正文与向量	知识库存在期间保存	删除知识库时联动清理
工具审计	有限期限、脱敏保存	企业策略控制
诊断日志	滚动、限额、脱敏	查看、导出和清除

7. 技术架构

7.1 逻辑架构

React Renderer
    │
    │ 强类型、白名单 IPC
    ▼
Electron Main Process
    ├── Window / Tray / Shortcut
    ├── Permission Broker
    ├── Context Broker
    ├── Model Gateway
    ├── Tool Orchestrator
    ├── Task Runtime
    ├── Update Manager
    └── Secure Storage
          │
          ├── SQLite
          ├── Attachment Storage
          ├── Vector Index
          └── Optional Rust Sidecar

7.2 进程职责

Renderer

页面和组件渲染。
用户交互和状态展示。
不直接访问 Node.js、文件系统、密钥和子进程。

Preload

通过 contextBridge 暴露最小、稳定、强类型 API。
不暴露通用 ipcRenderer、文件系统和命令执行接口。

Main Process

窗口、托盘、快捷键、权限、系统集成和应用生命周期。
模型请求、工具编排、安全存储和更新。
IPC 来源、参数和权限校验。

Rust Sidecar

仅在以下场景引入：

文档解析、OCR、向量索引等性能敏感工作。
Electron/Node 无法稳定支持的系统能力。
需要跨平台统一实现的受控本地服务。

Sidecar 必须具备版本握手、生命周期管理、超时取消、崩溃恢复、结构化协议和签名/哈希校验。

7.3 Electron 安全基线

contextIsolation: true。
nodeIntegration: false。
启用严格 CSP，禁止远程脚本执行。
IPC 使用白名单，并校验请求和响应 Schema。
外部链接使用系统浏览器打开，并校验协议和域名。
不可信页面不能使用特权 preload。
深度链接、自定义协议和文件路径必须规范化及校验来源。
Sidecar 使用固定可信路径，不拼接 Shell 命令。

7.4 本地存储

类型	建议存储
会话、消息、任务、权限、审计	SQLite
附件、解析缓存、缩略图	应用数据目录
向量索引	SQLite 扩展或独立索引
API Key 和令牌	系统安全存储

系统安全存储优先级：

Windows：Credential Manager 或 DPAPI。
macOS：Keychain。
Linux：Secret Service。
Linux 安全存储不可用时，提示用户配置或使用受密码保护的加密存储，不得静默降级为明文。

7.5 核心数据实体

实体	关键字段
Conversation	ID、标题、模型、创建/更新时间、隐私模式
Message	ID、会话 ID、角色、内容、状态、Token 信息
Attachment	ID、类型、来源、路径、哈希、大小、生命周期
ContextItem	ID、消息 ID、来源、摘要、授权范围
KnowledgeBase	ID、名称、嵌入模型、索引版本、状态
KnowledgeDocument	ID、知识库 ID、文件哈希、解析状态、版本
ToolDefinition	名称、版本、参数 Schema、风险等级、权限
ToolInvocation	工具、参数摘要、授权方式、状态、结果摘要
Task	ID、计划、当前步骤、状态、输出物
PermissionGrant	能力、作用域、有效期、来源
AppSetting	键、值、策略锁定状态

8. 跨平台兼容方案

8.1 发布矩阵

平台	架构	安装格式	优先级
Windows 10/11	x64	NSIS/MSIX	P0
Windows 11	ARM64	NSIS/MSIX	P0
macOS	Intel x64	DMG/PKG	P0
macOS	Apple Silicon	DMG/PKG	P0
Debian/Ubuntu/UOS/麒麟	x64	DEB/AppImage	P0
Debian/Ubuntu/UOS/麒麟	ARM64	DEB/AppImage	P0
RPM 系 Linux	x64/ARM64	RPM	P1

8.2 国产化环境要求

不假定统信 UOS、银河麒麟使用相同桌面环境、Wayland 版本和系统组件。
维护鲲鹏、飞腾 ARM64 真机或稳定远程测试环境。
检查 Electron、SQLite、OCR、向量库及 Sidecar 的 ARM64 构建。
尽量避免只提供 x64 预编译包的 Node 原生模块。
验证中文输入法、系统字体、多屏缩放、系统代理、证书存储和 Secret Service。
明确最低 glibc 和发行版基线，使用兼容构建环境产出 Linux 包。

8.3 X11 与 Wayland 差异

能力	X11	Wayland
任意窗口定位	通常可用	合成器可能禁止
全局快捷键	通常可用	依赖 Portal 或桌面设置
屏幕捕获	多种方式	优先 Portal/PipeWire
活动窗口信息	相对容易	通常受限制
模拟输入	技术上可行但高风险	通常禁止
置顶与穿透	依窗口管理器	行为不一致

实现时应使用能力检测，不只依赖操作系统名称判断。每个受限能力都必须提供替代入口。

9. 安全设计

9.1 主要威胁与控制

风险	场景	控制措施
提示注入	文档诱导 AI 上传数据或执行工具	文档视为不可信数据；独立权限层；高风险确认
越权文件访问	模型构造任意文件路径	文件句柄和授权范围；路径规范化；拒绝目录穿越
参数注入	URL、文件名或参数包含恶意内容	Schema 校验；不拼接 Shell；协议和域名白名单
凭据泄漏	日志、Renderer 或崩溃报告暴露密钥	安全存储；Main 注入；日志脱敏
恶意附件	宏、脚本、压缩炸弹	只解析不执行；资源限制；格式验证
更新供应链攻击	安装包或更新元数据被篡改	代码签名；元数据签名；TLS；回滚保护
IPC 攻击	被污染 Renderer 调用特权 API	隔离；最小桥接；来源和 Schema 校验
深度链接攻击	恶意协议参数打开本地资源	来源、协议、参数和路径校验
数据残留	临时截图和解析缓存未清除	明确生命周期；退出清理；可验证删除
自动化误操作	重复发送或覆盖文件	人工检查点；幂等键；冲突检测；审计

9.2 安全测试范围

IPC 参数伪造和越权调用。
路径穿越、符号链接和文件授权绕过。
深度链接及外部 URL 协议注入。
恶意 PDF、图片、压缩文件和超大文件。
提示注入导致工具越权。
更新签名失败、降级攻击和架构混装。
Renderer XSS、CSP 绕过和不可信导航。
日志、崩溃报告和诊断包敏感信息泄漏。

10. 非功能需求

10.1 性能

指标	MVP 目标
快捷面板热唤起	P95 ≤ 300ms
冷启动到可交互	P95 ≤ 3s，低配设备单独设基线
输入与滚动	无持续主线程阻塞，目标 50–60 FPS
首段内容展示	服务端返回首段后 500ms 内渲染
文件解析	后台执行，不阻塞 UI
空闲 CPU	不持续产生明显 CPU 占用
崩溃率	MVP 会话崩溃率 < 0.5%，正式目标 < 0.1%

10.2 可靠性

配置、会话和任务状态采用事务或原子写入。
主进程、Renderer 和 Sidecar 崩溃分别记录和恢复。
中断的副作用任务不得自动重放。
网络错误采用有上限的指数退避，避免重试风暴。
更新失败后可继续运行旧版本。
磁盘空间不足时停止写入并提示清理，不损坏已有数据。

10.3 可访问性

完整键盘导航和可见焦点。
基础屏幕阅读器语义。
字号、缩放和高对比度支持。
状态变化不只通过颜色表达。
动画支持减少动态效果设置。

10.4 国际化

MVP 支持简体中文。
文案、日期、数字和快捷键展示使用国际化资源。
预留英文支持。
不在代码中拼接不可翻译文案。

10.5 可观测性

监控以下脱敏指标：

冷启动、热唤起和窗口创建耗时。
首 Token、完整响应、取消成功率。
模型超时、限流和错误率。
文件解析、索引和检索耗时及成功率。
工具调用成功、拒绝、取消和超时率。
主进程、Renderer、Sidecar 崩溃率。
更新检查、下载、安装和回滚结果。
按平台、架构、X11/Wayland 拆分的兼容性数据。

遥测默认最小化，不采集消息全文、附件正文、剪贴板内容和截图，并允许用户或企业关闭。

11. 发布、测试与验收

11.1 测试层级

单元测试：模型网关、权限判定、参数校验、路径处理、数据转换。
组件测试：对话、附件、权限确认、工具步骤和设置界面。
集成测试：Renderer、Preload、Main IPC；数据库；安全存储；Sidecar。
端到端测试：首次启动、快捷唤起、对话、截图、文件、知识库和更新。
安全测试：恶意附件、IPC、深链、XSS、提示注入、凭据和更新链路。
兼容性测试：操作系统、架构、显示协议、DPI、输入法和权限状态。

11.2 最低兼容性矩阵

Windows 10 x64、Windows 11 x64。
Windows 11 ARM64。
macOS Intel、macOS Apple Silicon。
Ubuntu x64 的 X11 和 Wayland。
统信 UOS x64/ARM64。
银河麒麟 x64/ARM64。
鲲鹏与飞腾真机至少各一类。
单屏、多屏和不同 DPI。
常见中文输入法。
直连、系统代理、自定义代理和离线状态。
权限允许、拒绝和运行中撤销。
全新安装、覆盖升级、更新失败恢复和卸载。

11.3 MVP 功能验收

全局快捷键、托盘和主窗口都能进入核心对话。
文本、截图、剪贴板和文件都形成可见、可移除的上下文。
流式回答、停止、重试、复制和历史记录可用。
知识库回答带可打开的来源引用。
所有工具调用经过注册、参数校验和权限层。
权限拒绝后有明确降级方案，不崩溃、不循环申请。
用户可以清除会话、附件、知识库和诊断数据。
安装包与更新链路完成签名验证。

11.4 发布阻断项

Windows、macOS 安装包或更新包未完成代码签名。
macOS 未完成公证或 Hardened Runtime 验证。
x64/ARM64 架构混装或原生依赖缺失。
目标国产系统没有真机验证记录。
X11/Wayland 关键能力没有降级路径。
API Key 存在明文存储或日志泄露。
工具调用可绕过参数校验、确认或审计。
临时截图、附件和知识库无法完整删除。
更新失败会破坏当前可运行版本。
Renderer 可直接访问 Node.js 或不可信页面获得特权 API。

12. 迭代路线

阶段 0：技术验证

初始化 Electron + React + TypeScript + Vite 工程。
验证 x64/ARM64 多架构构建。
打通 Windows、macOS、Linux 安装与签名链路。
验证 X11/Wayland 快捷键、截图和窗口能力。
验证 UOS、麒麟、鲲鹏、飞腾原生依赖。
建立 Electron 安全基线、IPC Schema 和安全存储。
接入一个模型服务并完成流式对话。

退出条件：目标平台能够安装、启动、唤起、截图并完成一次对话，所有受限能力已有降级方案。

阶段 1：MVP

快捷面板、托盘、悬浮助手。
AI 对话和历史。
截图、剪贴板、文件和显式上下文。
单知识库 RAG。
白名单工具调用。
通知、设置、诊断、数据清理和更新。

退出条件：通过核心功能、兼容性、安全和性能验收。

阶段 2：效率与企业增强

多知识库、目录同步、OCR、混合检索和重排。
企业技能目录。
多步骤任务和人工检查点。
私有模型、企业代理、签名策略和审计。
灰度更新、回滚和企业更新源。

阶段 3：平台化

定时低风险自动化。
插件 SDK 和技能市场。
团队知识库、SSO、SCIM 和集中设备管理。
跨设备同步。
本地模型与混合推理。

13. MVP 建议开发拆分

模块	主要交付物	前置依赖
工程基础	Electron 工程、构建、日志、配置、CI	无
桌面外壳	窗口、托盘、快捷键、单实例、开机启动	工程基础
安全与 IPC	Preload API、Schema、CSP、安全存储	工程基础
对话核心	会话、消息、流式渲染、模型网关	安全与 IPC
上下文	附件、截图、剪贴板、文件解析	桌面外壳、安全与 IPC
知识库	分块、嵌入、索引、检索、引用	文件解析、模型网关
工具系统	注册、风险分级、确认、执行、审计	安全与 IPC、对话核心
设置与权限	设置页、权限中心、数据清理	各系统模块
更新与发布	签名、自动更新、多平台安装包	工程基础
质量体系	单元、集成、E2E、安全和兼容测试	全部模块

建议先完成阶段 0 的平台验证，再冻结 MVP 的详细交互稿和接口契约。国产 Linux 上的快捷键、截图、悬浮窗和原生依赖验证应前置，避免功能完成后才发现平台能力无法交付。

38 KiB Raw Blame History Unescape Escape

GoodBuddy 跨平台 AI 桌面助手功能方案设计

1. 文档信息

2. 产品定位

2.1 产品愿景

2.2 核心价值

2.3 目标用户

2.4 产品原则

2.5 当前非目标

3. 版本范围

3.1 优先级定义

3.2 MVP 核心闭环

3.3 版本能力概览

MVP

P1

P2

4. 产品信息架构

4.1 产品入口

4.2 主窗口导航

4.3 核心状态

5. 详细功能设计

5.1 首次启动与初始化

用户目标

功能项

异常与降级

MVP 验收

5.2 快捷唤起与快捷面板

用户场景

功能项

边界条件

降级策略

MVP 验收

5.3 系统托盘与应用生命周期

功能项

边界条件

MVP 验收

5.4 悬浮助手

功能项

边界条件

MVP 验收

5.5 AI 对话

功能项

关键交互

异常与边界

MVP 验收

5.6 上下文采集与上下文胶囊

上下文来源

交互规则

上下文等级

禁止行为

5.7 截图与 OCR

功能项

平台策略

MVP 验收

5.8 剪贴板

功能项

边界条件

MVP 验收

5.9 文件处理

MVP 支持格式

P1 支持格式

功能项

安全要求

MVP 验收

5.10 本地知识库

用户场景

MVP 功能

P1 功能

推荐检索链路

边界条件

MVP 验收

5.11 模型服务

支持方式

模型网关职责

配置项

MVP 验收

5.12 技能与工具调用

MVP 内置工具

工具风险分级

调用流程

38 KiB

Raw Blame History