# GoodBuddy 长期助手功能规划

## 1. 文档目标

本文定义 GoodBuddy 从“安全对话助手”演进为“可长期使用的桌面工作助手”所需的产品能力、交互结构、数据模型、权限边界、实施阶段和验收标准。

规划参考 ChatGPT 桌面版的桌面上下文、Projects、Tasks、成果分屏体验，以及腾讯 WorkBuddy 的任务工作区、右侧栏、自动化、记忆和专家协作能力，但不依赖其私有实现。

## 2. 产品目标

GoodBuddy 应能够：

1. 持续组织项目、会话、任务、成果和记忆，而不是只保存聊天记录。
2. 在明确授权下理解文件、知识库、截图、应用窗口和浏览器上下文。
3. 以只读问答、计划审查和受控执行三种模式完成工作。
4. 在右侧工作栏中持续展示任务、上下文、成果、文件更改和预览。
5. 支持后台任务、定时任务、失败恢复和桌面通知。
6. 让所有记忆、权限、上下文和远程传输可见、可审查、可撤销。

## 3. 产品信息架构

### 3.1 桌面布局

```text
┌──────────────┬──────────────────────────────┬──────────────────────┐
│ 左侧导航     │ 主工作区                     │ 右侧工作栏           │
│              │                              │                      │
│ 项目         │ 对话 / 知识库 / 活动         │ 任务                 │
│ 会话         │                              │ 上下文               │
│ 自动化       │                              │ 成果                 │
│ 记忆         │                              │ 文件与更改           │
│ 设置         │                              │ 预览                 │
└──────────────┴──────────────────────────────┴──────────────────────┘
```

- 宽窗口：右侧栏固定显示，可拖动宽度。
- 中等窗口：右侧栏默认折叠，点击后覆盖主工作区右侧。
- 窄窗口：右侧栏作为全屏抽屉。
- 右侧栏在对话、知识库和活动视图之间保持状态。
- 知识图谱实体详情复用同一右栏容器，不再维护独立布局。

### 3.2 右侧工作栏

#### 任务

- 展示正在运行、等待审批、失败和最近完成的任务。
- 支持查看步骤、进度、耗时和执行来源。
- 支持取消、重试、恢复和打开关联会话。
- 待审批项目在所有视图中持续可见。

#### 上下文

- 展示本次请求使用的附件、知识库、截图、剪贴板和授权目录。
- 每项上下文显示来源、大小、发送状态和作用域。
- 支持预览、移除和清空。
- 不显示或持久化用户未主动选择的桌面内容。

#### 成果

- 展示任务生成的文档、表格、演示文稿、PDF、图片、代码和网页。
- 支持打开、导出、在文件管理器中显示和继续修改。
- 成果必须关联项目、任务、运行和会话。

#### 文件与更改

- 展示当前项目工作区文件树。
- 展示创建、修改和删除文件。
- 文本文件提供 Diff，支持接受、撤销和在外部应用打开。
- 高风险变更继续经过独立审批层。

#### 预览

- 首期支持 Markdown、纯文本、JSON、图片和安全本地网页预览。
- 后续支持 PDF、Office 文档和数据表格。
- 网页预览使用隔离环境，不允许任意 Node.js 或 Electron API。

## 4. 核心功能

### 4.1 Projects 工作区

每个项目包含：

- 名称、说明、根目录和状态。
- 独立会话列表、任务、成果、记忆和自动化。
- 默认工作模式、Runtime、模型连接、Skills、MCP 和知识库范围。
- 项目可归档、恢复和导出。

会话支持置顶、归档、重命名、删除、按项目筛选和搜索。

### 4.2 工作模式

#### Ask

- 默认只读。
- 允许读取明确授权的上下文。
- 禁止文件写入、命令执行和外部副作用。

#### Plan

- Runtime 可读取上下文并生成结构化计划。
- 用户确认计划后才能进入 Execute。
- 计划变更需要重新确认。

#### Execute

- 允许按现有逐工具审批机制执行。
- 执行快照固定工作目录、模型、技能、MCP 和权限策略。
- 设置变化不影响正在运行的任务。

### 4.3 后台任务

- 任务状态：排队、运行、等待审批、暂停、完成、失败、取消、中断。
- 应用隐藏后任务继续运行，应用退出后不承诺继续执行。
- 重启时将未完成任务标记为中断，并允许用户恢复。
- 任务事件先持久化，再发送给 Renderer，避免窗口刷新后丢失。
- 父任务取消时必须取消所有子任务。

### 4.4 长期记忆

记忆作用域：

- 全局：用户偏好和通用习惯。
- 项目：术语、约定、目标和工作方式。
- 会话：仅在当前对话中使用。

记忆状态：

- 建议：模型提出，尚未启用。
- 已确认：允许参与后续上下文。
- 已拒绝：不再自动建议相同内容。

用户可以查看、搜索、编辑、确认、拒绝、删除和要求忘记。敏感个人信息不得自动确认为长期记忆。

### 4.5 成果和预览

- 成果存储在应用管理目录或用户指定位置。
- 每个成果记录类型、MIME、校验值、大小、来源和更新时间。
- Renderer 只能通过受控 IPC 读取预览，不接收任意系统路径访问能力。
- 大文件采用流式或分页读取，并设定大小上限。

### 4.6 定时任务

- 支持单次、每日、每周、每月和受限 Cron 规则。
- 保存时区、有效期、错过执行策略和输出位置。
- 支持立即运行、暂停、编辑、删除和查看历史。
- 应用启动及系统恢复时重新计算待执行任务。
- 同一计划同一时间点不得重复执行。

### 4.7 桌面通知

- 任务完成、失败、等待审批和定时任务结果可触发通知。
- 点击通知打开对应项目、任务或会话。
- 通知内容默认不包含敏感上下文。

### 4.8 桌面上下文

首期采用显式选择：

- 当前活动窗口信息。
- 指定窗口截图。
- 指定浏览器页面内容。
- 文件、目录、剪贴板和屏幕区域。

不实现持续录屏、静默窗口监控或全局输入记录。授权策略可以持久化，采集内容默认不持久化。

### 4.9 语音

- 首期提供按住说话和语音转文字。
- 转写结果先进入可编辑输入框，不自动发送。
- 后续增加流式语音对话和文本转语音。
- 麦克风权限仅在可信主窗口、显式语音会话和用户操作后开启。
- 音频转写完成后默认删除。

### 4.10 远程委派

- 远程入口可从受信任 Webhook、企业 IM 或移动端创建任务。
- 默认仅允许使用明确配置的项目和能力。
- 文件、记忆和桌面上下文不得隐式上传。
- Token 使用系统安全存储加密。
- 所有远程任务记录来源、摘要、幂等键、权限和结果。
- 远程委派默认关闭。

### 4.11 专家与多 Agent

- 专家包含名称、职责、系统指令、模型策略和能力白名单。
- 主任务可创建受限子任务，并由专家并行执行。
- 必须限制最大层级、并发、耗时、Token、工具次数和成果大小。
- 子任务不能绕过父任务权限。
- 主 Agent 负责整合结果，子 Agent 不直接向同一消息流并发写入。

## 5. 数据与持久化

新增独立 `assistant.sqlite`，不修改现有 `knowledge.sqlite`。

核心实体：

- `projects`
- `work_modes`
- `conversations`
- `messages`
- `tasks`
- `runs`
- `task_events`
- `artifacts`
- `memory_items`
- `schedules`
- `schedule_runs`
- `notifications`
- `experts`
- `delegations`

数据库要求：

- WAL、外键、事务化迁移。
- 所有状态变更可恢复。
- 敏感 Token 不写入 SQLite。
- 本地存储迁移成功后才删除旧数据。
- 支持数据导出和彻底删除。

## 6. 安全与隐私

1. 所有新 IPC 继续执行 Zod 校验和可信主窗口校验。
2. 项目根目录、成果路径和上下文路径必须 canonicalize 并验证目录包含关系。
3. Child Runtime 环境变量改用最小 allowlist，避免继承无关密钥。
4. 远程委派仅允许 HTTPS，开发环境只放行 loopback。
5. 语音、窗口捕获和浏览器上下文分别授权。
6. 自动化不得绕过工具审批和项目权限。
7. 记忆必须保留来源和作用域。
8. 所有模型输入继续按“不可信数据”处理。

## 7. 实施阶段

### 阶段 0：持久化基础

- 新增 `assistant.sqlite` 和迁移框架。
- 将会话与活动从 `localStorage` 迁移到主进程数据库。
- 拆分共享契约和 IPC 注册。
- 保持现有对话、知识库、设置和审批行为不变。

### 阶段 1：长期工作区骨架

- Projects 与会话归属。
- Ask、Execute 工作模式与旧版 Plan 数据兼容。
- 全局右侧栏。
- 任务、上下文、成果、文件更改和预览页签。

### 阶段 2：后台任务

- 持久化任务、运行和事件。
- 取消、重试、恢复和审批收件箱。
- 托盘状态和桌面通知。

### 阶段 3：成果与记忆

- 成果存储和安全预览。
- 项目记忆、确认流程和检索。
- 统一上下文组装器。

### 阶段 4：自动化与桌面上下文

- 定时任务和执行历史。
- 窗口选择、活动应用和浏览器上下文。

### 阶段 5：语音

- 按住说话、转写适配器和可编辑转写。
- 后续扩展实时语音与 TTS。

### 阶段 6：专家与远程委派

- 专家注册和受限子任务。
- 多 Agent 编排。
- 企业 IM/Webhook 远程入口。

## 8. 验收标准

### 8.1 右侧栏

- 三种窗口宽度下布局可用。
- 跨主视图切换保持页签和折叠状态。
- 任务、上下文和成果更新不要求离开当前对话。
- 键盘可操作，并具备正确 ARIA 标签。

### 8.2 Projects

- 创建、编辑、归档和恢复项目。
- 项目切换不会泄漏其他项目的上下文、记忆或任务。
- 旧会话可迁移且不丢失。

### 8.3 任务

- 事件持久化后再展示。
- 取消、失败、重试和应用重启均有确定状态。
- 审批在全局右侧栏可见。

### 8.4 记忆

- 未确认记忆不会进入模型上下文。
- 用户删除后不再检索到。
- 每条记忆显示来源与作用域。

### 8.5 安全

- Renderer 无任意文件读取能力。
- Runtime 无无关进程环境变量。
- 自动化和远程入口不能绕过审批。
- API Key、连接 Token 和音频不以明文长期保存。

### 8.6 质量门禁

- `npm run typecheck`
- `npm run lint`
- `npm test`
- 阶段里程碑执行 `npm run build`
- 发布前执行 packaged GUI smoke、依赖审计和 secret scan
