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

## 1. 文档信息

| 项目 | 内容 |
| --- | --- |
| 产品代号 | 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 上的快捷键、截图、悬浮窗和原生依赖验证应前置，避免功能完成后才发现平台能力无法交付。
