# 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 核心价值 1. **随时可用**：通过全局快捷键、系统托盘或悬浮助手快速唤起。 2. **理解当前工作**：在用户明确授权后读取选中文本、截图、剪贴板和文件。 3. **回答有依据**：知识库回答提供文件、页码或段落引用。 4. **执行可控制**：工具调用必须经过权限校验、参数校验和必要的用户确认。 5. **跨平台可交付**：在 Windows、macOS、Linux x64/ARM64 上保持核心任务一致。 6. **企业可治理**：支持模型、网络、权限、数据和更新策略的集中管控。 ### 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 核心闭环 ```text 安装并完成模型配置 → 使用快捷键唤起 → 输入问题或添加文本、截图、剪贴板、文件 → 查看本次将发送的上下文 → 获得流式回答和来源引用 → 复制结果或确认执行低风险工具 → 在历史记录中继续对话 ``` ### 3.3 版本能力概览 #### MVP - 主窗口、快捷面板、系统托盘、全局快捷键。 - 可关闭的悬浮助手。 - 多轮 AI 对话、流式输出、停止、重试和历史记录。 - 用户主动添加的截图、剪贴板、选中文本和文件上下文。 - 单个本地知识库、向量检索和来源引用。 - 白名单内置工具及逐次授权。 - 基础通知、设置、权限中心、诊断日志和更新检查。 - Windows、macOS、Linux x64/ARM64 安装包与兼容性验证。 #### P1 - 多知识库、文件夹同步、增量索引、OCR、混合检索和重排。 - 企业私有模型、代理网络、企业技能目录和签名策略。 - 多步骤任务、人工检查点、失败重试和任务历史。 - 更新灰度、回滚、企业更新源和审计导出。 - 更完善的活动窗口、选中文本及上下文白名单能力。 #### P2 - 定时低风险自动化和多步骤智能代理。 - 插件 SDK、技能市场和团队知识库。 - SSO、SCIM、集中设备管理和跨设备会话同步。 - 离线本地模型及云端、本地混合推理。 --- ## 4. 产品信息架构 ### 4.1 产品入口 | 入口 | 主要功能 | | --- | --- | | 系统托盘/菜单栏 | 打开助手、新建对话、暂停上下文能力、设置、退出 | | 全局快捷键 | 唤起或收起快捷面板 | | 悬浮助手 | 查看状态、打开快捷面板、进入常用动作 | | 主窗口 | 管理对话、知识库、技能、任务、通知和设置 | | 系统通知 | 跳转到已完成、失败或待确认的任务 | | 深度链接 | 在可信来源下打开指定会话或功能页面 | ### 4.2 主窗口导航 ```text 主窗口 ├── 对话 │ ├── 会话列表 │ ├── 消息区域 │ ├── 上下文附件 │ └── 输入与快捷动作 ├── 知识库 │ ├── 知识库列表 │ ├── 文档与索引状态 │ └── 检索测试 ├── 技能与任务 │ ├── 可用技能 │ ├── 权限范围 │ └── 任务历史 ├── 通知中心 └── 设置 ├── 通用与外观 ├── 模型服务 ├── 快捷键与悬浮助手 ├── 权限与隐私 ├── 存储与知识库 ├── 网络与代理 ├── 通知与更新 └── 诊断与关于 ``` ### 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、表格、代码块、公式和引用渲染。 - 代码复制、消息复制、反馈和导出。 - 会话标题自动生成，允许手动修改。 - 消息附件、工具调用步骤和来源引用。 - 上下文窗口及预计使用量提示。 - 网络失败后的重试和续接策略。 #### 关键交互 1. 用户发送后立即创建用户消息和助手占位消息。 2. 首段内容到达后进行增量渲染。 3. 工具调用显示为独立步骤卡片，不与普通文本混合隐藏。 4. 用户停止后立即中断网络请求和后续工具步骤。 5. 引用标记可打开原始文件、页码或文本片段。 #### 异常与边界 - 模型超时、限流、拒答或返回格式异常。 - 流式连接中断，仅收到部分内容。 - 上下文超过模型限制。 - 用户重复发送、快速切换模型或删除生成中的会话。 - 超长消息导致渲染性能下降。 #### 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、重复文件识别。 - 企业知识库及权限继承。 #### 推荐检索链路 ```text 文档解析 → 结构化清洗 → 保留标题、页码、偏移的分块 → 嵌入生成 → 向量/关键词混合检索 → 重排 → 上下文预算裁剪 → 带引用生成 → 引用一致性检查 ``` #### 边界条件 - 嵌入模型变化导致向量不兼容。 - 文件更新、重复导入、磁盘空间不足。 - 中文分块效果、扫描 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 禁止 | #### 调用流程 ```text 模型建议调用 → 检查工具是否注册 → 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 权限申请原则 1. 在首次使用具体能力前解释用途并申请。 2. 提供一次、当前会话、长期允许和拒绝选项。 3. 长期授权可在权限中心撤销。 4. 拒绝权限后不重复打扰，并提供替代路径。 5. 操作系统权限被撤销后立即停止能力并更新 UI 状态。 6. 高风险能力不能通过一次授权永久放行。 ### 6.3 敏感信息保护 - 本地检测 API Key、访问令牌、密码、身份证号、银行卡号等常见敏感模式。 - 检测结果只作为风险提示，不宣称完全准确。 - 企业策略可阻止特定数据发送给外部模型。 - 日志不记录完整提示词、附件正文、截图、密钥和令牌。 - 提供隐私模式：不保存会话、不保留附件、不写入知识库。 ### 6.4 数据生命周期 | 数据 | 默认策略 | 用户控制 | | --- | --- | --- | | 对话消息 | 本地保存，企业策略可覆盖 | 删除单条、会话或全部历史 | | 临时截图 | 请求或会话结束后清理 | 立即删除 | | 文件解析缓存 | 文件仍被引用时保存 | 单文件或统一清理 | | 知识库正文与向量 | 知识库存在期间保存 | 删除知识库时联动清理 | | 工具审计 | 有限期限、脱敏保存 | 企业策略控制 | | 诊断日志 | 滚动、限额、脱敏 | 查看、导出和清除 | --- ## 7. 技术架构 ### 7.1 逻辑架构 ```text 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 上的快捷键、截图、悬浮窗和原生依赖验证应前置，避免功能完成后才发现平台能力无法交付。