diff --git a/FEATURES.md b/FEATURES.md index 21e12ad..49683d7 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -16,6 +16,7 @@ - [x] **文件、截图、窗口、剪贴板上下文**：用户明确选择后才加入模型上下文。 - [x] **富文本回答**：支持 GitHub Flavored Markdown、LaTeX 数学公式和受控 Mermaid 图表；大图可缩放、拖动或查看源码，失败时保留原始图表代码。 - [ ] **项目 Agent Space**（规划中）：在 Project 中统一角色、知识、Skills/MCP、模型、审批策略、预算和超时，并支持模板复用。 +- [ ] **通用助手工作栏与执行空间**（规划中）：保留 Task Center 作为 Task 的单例索引，并把监督、Runtime、终端、进程、工作区、浏览器、成果和上下文作为始终可访问的应用级能力；除 Task Center 外的可绑定能力由用户选择跟随或固定目标，并逐步支持静态安全 HTML 预览、本机/SSH 执行空间和远程 Agent Runtime。详见 [Feature PRD](./docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。 ### Agent Runtime 与模型连接 @@ -32,8 +33,8 @@ - [x] **OpenCode Runtime 定制**：GoodBuddy 管理的内置 OpenCode 可发现原生 Agents、Tools、Commands、LSP、Formatters、MCP、Skills、Prompts 与 Resources；Tools 单独显示读取、文件修改、命令、网络、Agent 编排等类型、来源及 Ask/Execute 可用性，并隐藏 OpenCode 内部 `invalid` 与 GoodBuddy 临时 MCP 工具。支持保存默认 Agent、每次请求覆盖 Agent、通过原生 SDK 执行 Command、显示上下文用量并调用原生 Compact；外部 OpenCode Server 只报告连接状态，不宣称原生清单可读。任意插件安装、Session Share、自动 Worktree 和 OpenCode 原生会话持久化仍不开放。 - [x] **Continue Runtime 定制**：提供静态配置中的原生 Rules、Prompt 模板与 MCP 清单，以及可编辑的 GoodBuddy Rules/Prompt 配置预设；聊天可按请求选择预设和填入可继续编辑的 Prompt。当前 Continue Host 没有可信的静态原生 Tool 发现接口，且使用隔离的 `CONTINUE_GLOBAL_DIR`，因此界面明确标记 Tools 不支持静态发现，也不把 Host 实际不会加载的工作区或用户 Skills 冒充原生能力；GoodBuddy 分配的 Skills 仍按请求暂存执行。Continue 临时 Host 不复用原生会话压缩，手动压缩由 GoodBuddy 摘要模型完成并验证持久化摘要覆盖范围；Agent 交互提问转换为统一问答卡片。Resources、Hooks、后台 Job 和 Continue 原生会话管理继续暂缓。 - [x] **Runtime 原生清单语义**：原生能力以 Agents、Tools、Commands、Skills、MCP、Rules、Prompts、Resources、LSP、Formatters 和上下文 11 个页签展示；清单状态独立于 Runtime 连通性，区分完整、部分、不可用、仅连接和不支持。DeepSeek Harness 通过 Host Registry 枚举有界的内置/插件 Tools 与 Skills，显示真实 Ask/Execute 边界，并排除 GoodBuddy 按请求分配的 Skills、Web/MCP 代理。 -- [ ] **Runtime 监督侧栏**（规划中）：在聊天右侧助手工作栏统一承载 OpenCode、Continue 和 DeepSeek Harness 的 Subagent 控制、后台 Job、Workflow/Hook、长任务与原生会话监督；Composer 只保留对当前消息生效的高频上下文选择。 -- [ ] **可执行 Subagent**（规划中）：提供显式 Execute 委派，限制嵌套、并行、Token、时间和工具权限，在右侧 Runtime 监督页签显示父子状态、取消入口和审计归属。 +- [ ] **Runtime 监督栏目**（规划中）：在应用级助手工作栏的固定 Runtime 栏目统一承载 OpenCode、Continue 和 DeepSeek Harness 的 Subagent 控制、后台 Job、Workflow/Hook、长任务与原生会话监督；当前会话只提供默认目标，用户可以改为固定其他 Run，Composer 只保留对当前消息生效的高频上下文选择。 +- [ ] **可执行 Subagent**（规划中）：提供显式 Execute 委派，限制嵌套、并行、Token、时间和工具权限，在助手工作栏固定的 Runtime 栏目显示父子状态、取消入口和审计归属。 ### Skills、MCP 与知识库 @@ -55,8 +56,11 @@ ### 工作管理、长期协作与工作流 -- [x] **任务、活动与成果**：集中管理任务状态、审计活动和成果文件；Token 用量按 Runtime 与模型归类，并针对 OpenAI 兼容与 Anthropic Messages 的不同上报口径归一化展示缓存命中率；活动按会话分组并默认收起，避免长历史占满页面。 -- [x] **记忆与智能心跳**：提供周期回顾、建议记忆、洞察、后续任务和可审计运行轨迹。 +- [x] **任务、活动与成果**：集中管理任务状态、审计活动和独立成果文件；普通聊天回复只保留在会话中，不再自动复制到成果栏，已有重复聊天 Markdown 从成果列表隐藏但不物理删除。Token 用量按 Runtime 与模型归类，并针对 OpenAI 兼容与 Anthropic Messages 的不同上报口径归一化展示缓存命中率；活动按会话分组并默认收起，避免长历史占满页面。 +- [ ] **Task Center 完善**（规划中）：保留现有 Task Center，不先建设独立 Automation Center；Task 与唯一 Conversation 一对一，Task Center 只索引 Task，并补齐范围、状态、最近进展、需要关注和直接打开。普通 Conversation、Job、Run、工具步骤与心跳事项不作为顶层 Task。详见 [Task Center PRD](./docs/prd/task-and-job/task-center-prd.md)。 +- [x] **记忆与智能心跳**：当前提供周期回顾、建议记忆、洞察、后续任务和可审计运行轨迹。 +- [x] **智能心跳入口与范围改善**：将“智能心跳 > 心跳计划”作为完整配置的唯一权威入口，支持创建和编辑 Global 或指定一个、多个 Project 的计划；旧单项目配置无损迁移，项目级记忆与行动输出必须显式指定范围内的 Project。Task Center 和设置不再复制心跳表单。“未来分区记忆”仍只是尚待独立设计的长期方向。详见 [智能心跳 PRD](./docs/prd/smart-heartbeat/smart-heartbeat-prd.md)。 +- [ ] **通用监督**（规划中）：通过固定监督栏目观察用户选择的会话、任务、自动化或实验对象，提供带证据的评论与人工介入请求，但不自动发言、批准工具或切换 Execute。详见 [会话监督 PRD](./docs/prd/supervision/conversation-supervision-prd.md)。 - [ ] **批量运行与对比实验室**（规划中）：对模型、Prompt、角色和工作流配置执行批量对比，汇总质量、耗时、Token、费用、失败率和成果差异。 - [ ] **时态记忆与事实冲突检测**（规划中）：为记忆和知识图谱增加有效期、当前事实、过期与矛盾检测、事实核验及证据回溯。 - [ ] **可视化受控工作流**（规划中）：提供版本化 DAG、条件分支、审批、取消和恢复，执行节点继续经过 Main Runtime 边界。 @@ -86,6 +90,7 @@ - [x] **远程任务委派**：仅在用户显式配置端点和令牌后启用，按全局内网兼容模式使用 HTTP(S)，结果进入持久化发件箱。 - [ ] **Headless Runtime API**（规划中）：提供本机优先的任务、事件、状态和成果 API，以及有范围、有效期、限流和撤销能力的令牌。 - [ ] **GoodBuddy Team Hub**（规划中）：以可选服务提供组织、RBAC、项目共享、远程 Agent、策略下发和租户审计。 +- [ ] **SSH 主机与远程执行空间**（规划中）：管理 Host Key 固定和 Main-only 加密凭据，通过版本化远程 Helper 提供有界工作区、终端、受管进程和 Agent Runtime；远程执行继续遵循 Ask/Execute、审批、取消、超时和审计边界。 - [ ] **多云远程沙盒 Agent**（规划中）：通过云厂商 API 和 SSH Agent 管理专用 Linux 沙盒；凭据留在 Main 进程，高风险控制面操作单独确认。 ## 规划原则 diff --git a/README.en.md b/README.en.md index 7b03d1b..2c7cb7b 100644 --- a/README.en.md +++ b/README.en.md @@ -27,7 +27,9 @@ A secure, cross-platform, local-first desktop AI assistant and Agent workspace. ![GoodBuddy Smart Heartbeat](docs/screenshots/smart-heartbeat.png) -See [FEATURES.md](FEATURES.md) for the detailed feature matrix and roadmap. +See [FEATURES.md](FEATURES.md) for the detailed feature matrix and roadmap, and +the [documentation index](docs/README.md) for product, architecture, design, +and quality documents. ## Install diff --git a/README.md b/README.md index 0b2555e..d852199 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ ![GoodBuddy 智能心跳](docs/screenshots/smart-heartbeat.png) -完整功能和路线图见 [FEATURES.md](FEATURES.md)。 +完整功能和路线图见 [FEATURES.md](FEATURES.md)，产品、架构、设计与质量文档见 +[文档导航](docs/README.md)。 ## 安装 diff --git a/UI-DESIGN.md b/UI-DESIGN.md index dcb1fe2..763ef23 100644 --- a/UI-DESIGN.md +++ b/UI-DESIGN.md @@ -2,7 +2,8 @@ ## 1. 目的与适用范围 -本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、知识库、智能心跳、运行记录，以及后续新增的一级页面。 +本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、任务中心、知识库、 +智能心跳、运行记录，以及后续新增的一级页面。 设计系统解决两类问题： @@ -144,7 +145,7 @@ | 变体 | 最大内容宽度 | 适用场景 | 页面映射 | | --- | --- | --- | --- | | `reading` | `820px` | 连续阅读、单列编辑、对话撰写 | 聊天正文与输入区 | -| `standard` | `960px` | 常规列表、设置、表单与任务管理 | 最近对话、任务 | +| `standard` | `960px` | 常规列表、设置与表单 | 最近对话、设置 | | `dashboard` | `1040px` | 指标、卡片网格、宽表格与审计数据 | 智能心跳、活动记录 | | `master-detail` | 可用空间内流式铺开 | 左侧选择、右侧编辑或预览 | 知识库 | @@ -192,7 +193,7 @@ ### 6.1 PageTabs -用于同一一级页面内的同级内容面板，例如心跳的“成长概览”和“心跳计划”。 +用于同一一级页面内的同级内容面板，例如智能心跳的“成长概览”和“心跳计划”。 - 使用 `tablist`、`tab` 和 `tabpanel` 语义，当前项使用 `aria-selected="true"`。 - 一级页面之间的导航由应用主导航承担，不复用 `PageTabs`。 @@ -283,7 +284,24 @@ - 未选中项保持平整，不为每一行添加卡片边框或阴影。悬停反馈不得强于选中状态。 - 账户与设置入口固定在侧栏底部。已有稳定设置入口时，不在顶栏重复提供同一入口。 -### 6.9 应用顶栏与全局操作 +### 6.9 助手工作栏 + +助手工作栏是应用级右侧工具容器，不归属于聊天页面，也不根据当前页面、项目或 Runtime +自动增删入口。产品契约见 +[通用助手工作栏与执行空间 PRD](./docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。 + +- 默认固定提供 Task Center、监督、Runtime、终端、进程、工作区、浏览器、成果和上下文九个标准栏目。 +- Task Center 是 Task 的单例应用级索引，不使用“跟随 / 固定目标”多实例模式。每个 Task + 与唯一 Conversation 一对一绑定，列表不得复制会话内容，也不得把 Job/Run 单独提升为 Task。 +- 其他可绑定目标的栏目独立支持“跟随当前上下文”和“固定到指定对象”。当前会话、项目和 Runtime 只提供默认目标，不能成为进入栏目或切换目标的前提。 +- 能力、连接和内容可以动态变化，栏目入口不能随之自动隐藏。不可用状态必须说明原因、影响和可执行入口。 +- 用户可以主动排序或隐藏栏目，并可恢复默认布局；应用不能用用户偏好机制实现自动能力裁剪。 +- 九个栏目优先使用带稳定图标与标签的纵向工具导航，并保留 `tablist`、`tab`、`tabpanel`、方向键、Home、End 和焦点恢复语义。 +- 徽标可以提示未解决意见、等待审批、失败或连接状态，但不能成为唯一状态信号，也不能无条件抢占当前栏目。 +- 宽窗口可停靠并调整宽度，中等窗口可停靠或覆盖，窄窗口使用全屏或接近全屏抽屉；所有尺寸下均须保留全部栏目入口。 +- 终端、宽日志和大型成果可以由用户切换到底部停靠或独立窗口，应用不得因内容变化自动改变用户已选布局。 + +### 6.10 应用顶栏与全局操作 应用顶栏用于窗口级状态、侧栏开关和低频全局操作，不承担页面标题或主要导航。顶栏必须保持紧凑，不能与页面内容争夺注意力。 @@ -295,7 +313,7 @@ - 窄窗口下优先压缩状态标签并保留图标按钮，不隐藏窗口控制、当前范围或进行中的风险状态。 - 使用全局菜单时，菜单项使用 `--font-body`、`14px` 图标和约 `32px` 单项高度；标签使用短名称。菜单保留 `menu`、`menuitem` 语义，支持上下方向键、Home、End 和 Escape，关闭后焦点返回触发按钮。 -### 6.10 上下文单选菜单 +### 6.11 上下文单选菜单 模型、专家角色、工作模式、Runtime Agent、Runtime 预设和 Runtime 快捷操作属于同一输入上下文，其选择器必须共享结构、尺寸和菜单视觉，不能出现一个精细菜单与多个风格不一致的原生下拉框。 @@ -306,7 +324,7 @@ - 不可用选项保持可读并说明原因，键盘导航不得停留在不可选择项上。 - 仅在选项简单且不需要说明、禁用原因或一致菜单行为时使用原生 `select`。 -### 6.11 应用通知与就地反馈 +### 6.12 应用通知与就地反馈 应用级通知统一进入全局通知视口，页面不得自行复制通知卡片或在内容流中长期堆放短期消息。 @@ -317,7 +335,7 @@ - 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 `alert` 和 assertive 实时区域，成功与信息使用 `status` 和 polite 实时区域。 - 一个事件只能选择一种主要反馈位置，不得同时显示页内横幅和全局通知。失败时不得因通知切换而清空用户输入、筛选或未提交草稿。 -### 6.12 Switch 与 Checkbox +### 6.13 Switch 与 Checkbox Switch 用于在两个持久状态之间立即切换，例如启用能力、开启索引、允许群消息或显示平台入口。Checkbox 用于独立多选、范围分配或执行前确认，例如选择多个 Runtime、选择知识库、清除已保存密钥。两者不得只因底层都使用 `input[type="checkbox"]` 而混用视觉或语义。 @@ -473,8 +491,8 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 - 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。 - 模型、专家角色、工作模式、OpenCode Agent、Continue 预设和 Runtime 快捷操作使用统一的上下文单选菜单，并保持菜单互斥、键盘可达和选中状态明确。 - 输入区第一行工具栏只承载附件、语音、知识范围、专家角色、工作模式、Runtime 选择和发送等通用操作。OpenCode Agent、Continue 预设及 Runtime 快捷操作必须放入其下方独立的 Runtime 专属功能行，通过可见分组名称、顶部边界和差异化表面与通用操作分层；该行只承载对当前消息生效的高频选择，当前 Runtime 没有可选专属功能时不保留空行。 -- OpenCode、Continue 和 DeepSeek Harness 后续的 Subagent 层级与取消、后台 Job 队列/进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止及原生会话监督统一进入右侧助手工作栏的“Runtime”页签，不加入 Composer。侧栏按当前会话和 Runtime 能力动态显示区块，不为未支持能力渲染空卡片或成排禁用按钮；切换会话或 Runtime 时必须同步清理上一归属的监督状态。 -- 设置中心只管理持久 Runtime 配置、默认值和能力清单；右侧 Runtime 页签只管理当前活动会话的生命周期。两处不得复制同一实时操作，侧栏中的高风险操作仍须就地确认并保留取消、权限、用量和活动审计。 +- OpenCode、Continue 和 DeepSeek Harness 后续的 Subagent 层级与取消、后台 Job 队列/进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止及原生会话监督统一进入应用级助手工作栏固定的“Runtime”栏目，不加入 Composer。栏目入口始终存在；内部可选区域按用户所选目标和 Runtime 的真实能力显示，不为未支持能力渲染空卡片或成排禁用按钮。切换跟随目标时必须清理上一归属的监督状态，固定目标则保持不变。 +- 设置中心只管理持久 Runtime 配置、默认值和能力清单；右侧 Runtime 栏目管理用户当前跟随或固定目标的生命周期。两处不得复制同一实时操作，栏目中的高风险操作仍须就地确认并保留取消、权限、用量和活动审计。 - Runtime Prompt 快捷操作只把模板填入输入草稿，用户可以继续编辑；OpenCode Command 由 Runtime 原生 API 执行，输入框只承载可选参数，不以普通斜杠文本冒充执行。 - Agent 回复进行中锁定模型、专家角色、工作模式和 Runtime 定制选择器，并关闭已打开的上下文菜单；回复结束或停止后再恢复选择，避免界面状态与本次运行实际使用的上下文不一致。 - 支持上下文状态的 Runtime 在输入区下方复用同一紧凑用量条；文案必须区分“本次模型调用”和“压缩后对话估算”。手动压缩仅在当前 Runtime 明确支持且没有活动回复时显示，作为元信息区左下角的浮动次操作，不参与输入区高度计算；元信息区始终预留稳定高度，切换 Runtime 不得让输入框上下位移。元信息区与窗口底部只保留紧凑安全留白，不形成额外空白区。进行中禁用重复操作，结果通过应用通知反馈。 @@ -504,11 +522,24 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 ### 13.4 智能心跳 - 使用 `dashboard` 壳层。 -- 顶部先呈现运行状态、当前范围和主操作，再呈现指标和配置。 +- 顶部先呈现运行状态、实际范围和主操作，再呈现指标、建议、历史与配置。 +- 范围明确区分 Global 与指定的一个或多个 Project；Global 与指定项目互斥，多项目选择使用 + Checkbox，不能依靠进入页面时的当前项目推断。 - 状态卡片使用统一状态令牌，不只依赖颜色。 -- 运行历史与配置使用明确区块，不以多套相似页签混合导航、开关和筛选。 +- 保留“成长概览 / 待处理建议 / 心跳轨迹 / 心跳计划”四个同级页面。 +- 智能心跳菜单入口是完整配置的权威位置；任务中心和设置中心不得复制同一 CRUD 表单。 +- “未来分区记忆”仅为长期方向，数据、状态和页面尚未设计，不得显示占位入口。 -### 13.5 运行记录 +### 13.5 Task Center + +- 保留现有助手工作栏入口，首期在窄栏内适度完善，不先扩张成新的独立一级页面。 +- 只展示 Task；普通 Conversation、Job、Run、工具步骤、Subagent 和心跳事项不独立占行。 +- 每项显示名称、Global 或 Project 范围、状态、最近进展、最近真实活动时间及需要关注信息。 +- 点击列表项直接打开 Task Conversation，不显示第二份内容载体。 +- 需要关注、进行中、已暂停和已结束使用共享 `SegmentedControl`；窄栏不足时单行滚动。 +- 完整消息、长错误、活动和成果留在 Task Conversation、Runtime、活动记录和成果查看器中，不撑高列表。 + +### 13.6 运行记录 - 使用 `dashboard` 壳层，并通过 `PageTabs` 提供“任务与会话 / 活动时间线 / 用量统计”三个同级视图。 - 默认视图按“项目 → 任务或会话 → 活动详情”组织，项目范围持续可见，任务或会话详情可以折叠。 @@ -517,14 +548,14 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 - 用量统计与活动记录分离，支持按项目、会话和模型切换统计维度，宽表格在独立容器内横向滚动。 - 活动状态筛选使用 `SegmentedControl`，不与页面页签混合。清空历史遵循破坏性操作政策。 -### 13.6 魔法笔记 +### 13.7 魔法笔记 - “笔记 / 待办”属于同一工作台内的同级内容面板，使用 `PageTabs` 的 `segmented` 视觉变体，与模型设置的分段控件保持同一外观。 - 页签切换保留 `tablist`、`tab` 和 `tabpanel` 语义；待办状态仍使用独立的 `SegmentedControl`，不得与内容页签合并。 - 创建、保存、更新、删除和 AI 评论完成等短期结果进入应用级通知，不在编辑区或列表上方堆放页内通知。 - 标题或正文校验、删除确认、同步进度和可就地恢复的错误仍靠近对应编辑器或操作呈现。 -### 13.7 设置中心 +### 13.8 设置中心 - 全页设置使用固定标题区、左侧分类导航和独立滚动的内容区。右上角关闭按钮是离开设置中心的稳定入口。 - 左侧分类导航在宽屏使用 `220px`，中等窗口使用 `196px`，窄窗口转为横向滚动；纵向滚动条仅在内容溢出时占用右侧空间，不在左侧创建镜像预留，选项与左侧可见边界保持默认内距。分类标题使用正文级字号，分类说明使用辅助字号；右侧内容区在可用空间内流式伸缩，最大宽度使用 `standard` 壳层的 `960px`，不得以页面专属较窄宽度压缩表单。 @@ -533,6 +564,8 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 - 所有分类使用共享的 `SettingsCategoryHeader` 呈现分类标题、说明、错误与操作，不得在内容卡片内复制分类标题或创建页面专属操作栏。左侧分类名称与说明来自同一份分类定义，新增分类时不得分别维护导航和内容标题。 - 当前分类存在“保存”或“测试”等未提交配置操作时，统一放在分类页头右侧；主保存操作在最右侧，测试等次操作排列在其左侧。 - 自动生效、仅执行即时命令或自行管理编辑流程的分类不显示全局保存操作。窄窗口下操作区可以换行，但保存入口必须保持清晰可见。 +- 智能心跳的单条配置不在设置中心重复管理。设置中心如需呈现平台级说明，只提供 + “打开智能心跳”导航，不复制创建、暂停、恢复或删除表单。 - 保存或测试成功统一进入应用通知视口，并按全局规则自动消失，不在分类页头或内容卡片中保留持久成功文案。加载、保存和测试错误显示在分类页头下方，并保留可处理的上下文。 - “关于与更新”的更新源位于“启动时检查新版本”开关下方，常规宽度下将标签、原生单选下拉框和用途说明放在同一行，并复用设置表单的统一控件样式；关闭启动检查后，下拉框置灰且不可操作。选项显示“GitHub（默认）”和中性的“镜像节点”。该选择同时控制手动检查、启动时检查和下载页，不显示底层服务商名称。 - Agent Runtime 分类页头的“保存设置”同时保存 Runtime 基础配置与 Runtime 原生定制，不在原生定制卡片内提供第二个保存入口。原生定制存在未保存更改时持续显示状态和撤销入口；切换设置分类或 Runtime 不丢弃草稿，关闭设置中心前必须先保存或撤销。 @@ -542,7 +575,7 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 - MCP 设置按“内置 MCP / 直连模型 / 自定义 MCP / 电脑控制”四个同级 `PageTabs` 组织。直连模型中的联网搜索与内置浏览器使用一致的折叠卡片和独立总开关；内置浏览器必须明确说明其操作 GoodBuddy 隔离浏览器，不控制客户端已安装的浏览器，开启后可由 Execute 直接使用，不逐次询问。尚未生效的命名浏览器配置不得显示在界面中，“电脑控制”只显示实际操作客户端电脑的能力。内置 MCP 卡片与 Skills 一样提供持久启停和 Runtime 分配；直连模型、GoodBuddy 管理的 OpenCode 与 Continue 默认选中且可调整，DeepSeek Harness 必须以置灰、未选择和“暂不支持”文案持续显示，不能呈现为可保存的分配。魔法笔记 MCP 的自身启停与平台功能依赖分别显示，依赖未开启时保留用户配置并说明当前不会加载。 - MCP Server 测试结果在同一展开卡片中分组显示 Tools、Prompts 和 Resources 的支持状态、数量与有界元数据；Prompt 参数标明必填项，Resource 只显示 URI、名称、类型和说明，不读取或渲染 Resource 内容。 -### 13.8 文档解析设置 +### 13.9 文档解析设置 - 设置中心新增独立的“文档解析”分类，统一管理聊天附件、知识库导入以及后续文档审阅场景使用的提取、转换和 OCR 策略。OCR 不作为普通对话模型出现在“模型连接”中。 - 分类页头说明文档解析的跨场景作用，右侧依次显示“测试解析”和“保存设置”；保存位于最右侧。测试必须选择真实文件并执行实际解析，不能只检查模型文件或接口连通性。 @@ -609,8 +642,9 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证 - [ ] 将输入快捷键与附件提示置于空输入框内部，输入区下方保持单行说明。 - [ ] 最近对话迁移到 `standard`，统一搜索、范围、时间和删除行为。 - [ ] 知识库迁移到 `master-detail`，清除内联浅色样式并补齐窄窗口单面板流程。 -- [ ] 智能心跳迁移到 `dashboard`，统一状态卡片、配置和运行历史层级。 -- [ ] 任务迁移到 `standard`，活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。 +- [x] 智能心跳使用 `dashboard`，保留概览、建议、轨迹和计划，并在计划中支持 Global / 多 Project 范围。 +- [ ] 在现有工作栏中完善任务中心，统一范围、状态、最近进展和筛选，不新建平行任务平台。 +- [ ] 活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。 - [ ] 设置中心使用共享分类定义与 `SettingsCategoryHeader`，将保存与测试操作统一放到分类页头右侧，并把成功反馈接入应用通知。 - [ ] 文档解析设置统一聊天附件与知识库的解析预设、OCR 状态、转换状态、隐私限制和真实文件测试。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..9c98d5a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,47 @@ +# GoodBuddy 文档导航 + +GoodBuddy 文档按“文档类型 → 功能域”组织。新增文档应先选择类型，再放入对应功能目录， +避免继续把所有设计平铺到单一 `features` 目录。 + +## 产品需求 + +| 功能域 | 入口 | +| --- | --- | +| Task 与 Job | [Task 与 Job 总览](./prd/task-and-job/README.md) | +| Smart Heartbeat | [智能心跳 PRD](./prd/smart-heartbeat/smart-heartbeat-prd.md) | +| 助手工作栏 | [通用助手工作栏与执行空间 PRD](./prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md) | +| 会话监督 | [会话监督 PRD](./prd/supervision/conversation-supervision-prd.md) | +| 记忆 | [分区记忆 PRD](./prd/memory/partitioned-memory-prd.md) | +| 并行实验 | [并行实验工作台 PRD](./prd/experiments/parallel-experiments-prd.md) | +| 持续学习 | [持续学习与评估门 PRD](./prd/learning/continuous-learning-prd.md) | +| 知识库 | [知识库检索与分块增强 PRD](./prd/knowledge/knowledge-rag-enhancement-prd.md) | +| 文档处理 | [文档解析与本地 OCR](./prd/document-processing/document-extraction-and-local-ocr.md) | +| 消息通道 | [微信 ClawBot 通道 PRD](./prd/channels/wechat-clawbot-channel-project-prd.md) | + +## Task 与 Job 文档 + +- [统一领域模型](./prd/task-and-job/task-and-job-model.md) +- [Task Center](./prd/task-and-job/task-center-prd.md) +- [Scheduled Task](./prd/task-and-job/scheduled-task-prd.md) +- [Goal Task](./prd/task-and-job/goal-task-prd.md) +- [Job 与 Subjob](./prd/task-and-job/job-and-subjob-prd.md) + +## 跨功能文档 + +- [自动化平台架构](./architecture/automation-platform-architecture.md) +- [DeepSeek Harness Runtime 设计](./architecture/deepseek-harness-runtime-design.md) +- [跨平台助手产品设计](./design/cross-platform-assistant-product-design.md) +- [长期助手路线图](./roadmap/long-term-assistant-roadmap.md) +- [电脑控制实施状态](./status/computer-control-implementation-status.md) +- [知识检索评估](./quality/knowledge-retrieval-evaluation.md) +- [统一界面设计系统](../UI-DESIGN.md) + +## 目录规则 + +1. PRD 放在 `docs/prd/<功能域>/`。 +2. 跨功能技术总纲放在 `docs/architecture/`。 +3. 产品级设计放在 `docs/design/`，路线图和实施状态分别放在 `roadmap`、`status`。 +4. 测试方法、评估协议和质量报告放在 `docs/quality/`。 +5. 一个概念只能有一份权威定义；其他文档链接到它，不复制另一套术语。 +6. Task、Job、Run、Subagent 和 Conversation 的含义以 + [Task 与 Job 统一领域模型](./prd/task-and-job/task-and-job-model.md) 为准。 diff --git a/docs/features/automation-platform-architecture.md b/docs/architecture/automation-platform-architecture.md similarity index 72% rename from docs/features/automation-platform-architecture.md rename to docs/architecture/automation-platform-architecture.md index 2b7de00..32cd396 100644 --- a/docs/features/automation-platform-architecture.md +++ b/docs/architecture/automation-platform-architecture.md @@ -5,39 +5,46 @@ | 项目 | 内容 | | --- | --- | | 状态 | 设计中 | -| 版本 | 0.1 | -| 日期 | 2026-08-13 | +| 版本 | 0.3 | +| 日期 | 2026-08-19 | | 适用产品 | GoodBuddy 桌面端 | -| 文档角色 | 自动任务、目标、并行实验、会话监督、分区记忆与持续学习的总纲 | +| 文档角色 | Task/Job、调度、目标、并行实验、会话监督、分区记忆与持续学习的总纲 | +| 领域模型 | [Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md) | ## 1. 背景 GoodBuddy 当前已经具备若干长期助手能力，但它们仍是彼此分离的功能： -1. 定时任务支持单次、每日和每周触发，创建 Ask 任务并保存任务和成果。 -2. 智能心跳支持全局或项目范围的每日、每周回顾，读取有界会话、任务和已确认记忆， +1. Scheduled Task 支持单次、每日和每周触发。一个 Task 绑定一条持续 Conversation， + 每次触发在其中创建 Job/Run 并保存进展和成果。 +2. 当前智能心跳支持全局或项目范围的每日、每周回顾，读取有界会话、任务和已确认记忆， 生成摘要、记忆建议和后续任务。 -3. 专家子任务支持有限并发和只读综合，但没有实验变量、重复运行、统一指标和结果晋升。 +3. 专家执行的 Job 支持有限并发和只读综合，但没有实验变量、重复运行、统一指标和结果晋升。 4. 记忆已有全局、项目、会话三种作用域，以及偏好、事实、摘要、流程四种类型， 但检索、来源、时态、冲突和运行级隔离仍不完整。 5. 魔法笔记已经提供“内容旁持续出现 AI 评论”的交互，可作为会话监督的体验参考， 但它只分析笔记或待办，不观察会话和任务运行。 -如果继续把更多能力加入“智能心跳”，心跳将同时承担调度、总结、执行、监督、学习和 -记忆管理，最终无法解释一次后台行为为什么发生、读取了什么、是否越权、产生了什么影响。 +智能心跳长期方向是面向未来的分区记忆，但该模型尚未设计。近期只改善现有心跳的权威入口 +与 Global / 多 Project 范围，并保留 Task Center 作为 Task 索引。若继续把 Task、调度、 +监督、学习和执行加入“智能心跳”，将无法解释一次后台行为为什么发生、读取了什么、是否 +越权、产生了什么影响。 本设计将这些能力统一到一个平台模型中，同时保留不同产品的清晰边界。 ## 2. 核心产品判断 -### 2.1 不把心跳升级成万能后台 Agent +### 2.1 智能心跳保持独立，未来分区记忆另行设计 -智能心跳应继续承担周期性观察和回顾，不直接成为所有自动化的宿主。 +当前智能心跳继续承担周期回顾、报告和建议，并支持 Global 或指定 Project 范围。它不是 +Task、通用调度器或后台 Agent，也不进入统一 `AutomationPlan.kind`。未来分区记忆的 +数据、状态、唤起和页面需要独立设计，不能从当前方向直接推导。 -- 定时任务解决“何时执行一个已知任务”。 -- 目标任务解决“围绕结果持续规划和推进”。 +- Scheduled Task 解决“何时在一个 Task 中执行新的 Job”。 +- Goal Task 解决“围绕结果在同一 Task 中持续规划和推进”。 - 并行实验解决“隔离多个候选并用相同标准比较”。 - 会话监督解决“独立观察并在必要时评论、告警或暂停”。 +- 智能心跳当前解决“在什么范围周期回顾并提出报告和建议”。 - 记忆系统解决“哪些经验可以在什么范围内被未来运行读取”。 - 持续学习解决“候选经验如何经过评估后改变未来行为”。 @@ -85,8 +92,8 @@ SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现 ### 3.1 用户目标 -- 用统一入口创建定时、事件、目标和实验型自动任务。 -- 清楚知道自动任务的触发原因、当前目标、运行状态、预算和停止条件。 +- 在现有 Task Center 中找到 Scheduled、Event 和 Goal Task，并直接打开 Task Conversation。 +- 清楚知道 Task 的触发原因、当前目标、Job 状态、预算和停止条件。 - 在一个工作台中观察多个候选运行，并追溯结论到原始证据。 - 为重要会话启用独立监督，及时发现偏题、遗漏、矛盾、证据不足和风险。 - 知道每条记忆属于哪个范围、从哪里产生、何时有效以及被哪些运行使用。 @@ -95,6 +102,7 @@ SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现 ### 3.2 产品目标 - 复用现有 Project、Conversation、Task、Run、Artifact、Approval 和 Notification 能力。 +- 保持一个 Task 只绑定一条 Conversation，不为同一项工作建立第二份内容载体。 - 为所有后台工作提供统一的幂等、租约、恢复、取消、预算和审计语义。 - 保持 Ask 只读，Execute 继续经过现有能力和审批控制。 - 保持本地优先，应用退出后不虚假承诺后台持续执行。 @@ -117,38 +125,46 @@ SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现 ## 5. 统一领域模型 +以下模型是 Scheduled Task、Goal Task 和实验共享的技术基础，不要求新增独立 +Automation Center。`AutomationPlan` 是 Task 的计划配置，`Job` 是 Task 内执行单位， +`Run` 是执行尝试。用户主要通过 Task Center 和 Task Conversation 理解工作。智能心跳 +不属于此模型。 + ### 5.1 核心实体 ```text -AutomationPlan - ├─ TriggerPolicy - ├─ ObjectiveSet - ├─ ExecutionProtocol - ├─ BudgetPolicy - ├─ ApprovalPolicy - ├─ SupervisorPolicy - └─ MemoryBinding - │ - └─ AutomationRun - ├─ Task / Child Task - ├─ Observation - ├─ SupervisorDecision - ├─ Artifact - ├─ Metric - └─ MemoryCandidate +Task ── Conversation + ├─ AutomationPlan（可选） + │ ├─ TriggerPolicy + │ ├─ ObjectiveSet + │ ├─ ExecutionProtocol + │ ├─ BudgetPolicy + │ ├─ ApprovalPolicy + │ ├─ SupervisorPolicy + │ └─ MemoryBinding + └─ Job + ├─ Run + ├─ Subjob + ├─ Observation + ├─ SupervisorDecision + ├─ Artifact + ├─ Metric + └─ MemoryCandidate ``` | 实体 | 职责 | | --- | --- | -| `AutomationPlan` | 用户可编辑的长期定义，描述做什么、为何做、何时做和允许做什么 | +| `Task` | 用户可见工作单位，与唯一 Conversation 一对一绑定 | +| `Job` | Task 内部一次步骤、触发、并行分支或委派执行 | +| `Run` | Task/Job 的一次执行尝试和审计记录 | +| `AutomationPlan` | Task 的可编辑计划配置，描述做什么、为何做、何时做和允许做什么 | | `TriggerPolicy` | 手动、时间、事件或条件触发，以及错过执行策略 | | `ObjectiveSet` | 成功标准、优化指标、约束和停止条件 | | `ExecutionProtocol` | 本次运行冻结的提示、步骤模板、变量、Runtime、工具和数据范围 | -| `BudgetPolicy` | 最大耗时、模型调用、Token、工具次数、子任务数、成果大小和并发 | +| `BudgetPolicy` | 最大耗时、模型调用、Token、工具次数、Job/Subjob 数、成果大小和并发 | | `ApprovalPolicy` | 哪些动作可自动执行、哪些等待批准、哪些禁止 | | `SupervisorPolicy` | 观察维度、触发频率、干预级别和确定性门禁 | | `MemoryBinding` | 运行可读取和可写入哪些记忆分区 | -| `AutomationRun` | 一次触发产生的不可变运行快照和聚合状态 | | `Observation` | 对消息、步骤、工具、指标或系统状态的结构化观察 | | `SupervisorDecision` | `continue`、`comment`、`warn`、`request_review`、`pause` 或 `stop` | | `Metric` | 可复现的运行指标及其计算来源 | @@ -161,12 +177,11 @@ AutomationPlan | 类型 | 说明 | | --- | --- | | `scheduled_task` | 到点运行一个固定任务 | -| `heartbeat_review` | 周期性观察会话、任务和记忆，输出回顾和建议 | | `goal_loop` | 围绕目标重复执行“观察、计划、行动、评估” | | `experiment` | 生成隔离候选 Run，按统一协议评估和比较 | -会话监督不是独立执行任务。它是可附着到 Conversation、Task、AutomationRun 或 -Experiment 的 `SupervisorPolicy` 和监督会话。 +会话监督不是独立 Task。它是可附着到 Conversation、Task、Job/Run 或 Experiment 的 +`SupervisorPolicy` 和监督会话。 ### 5.3 运行快照 @@ -237,7 +252,7 @@ inactive → observing → attention_required → paused → resolved Trigger → AutomationCoordinator 声明 Run → RunQueue 按优先级和预算排队 - → AutomationExecutor 创建 Task + → AutomationExecutor 在所属 Task 内创建或恢复 Job → Runtime 执行 → Supervisor 观察 → Evaluator 计算指标 @@ -245,8 +260,8 @@ Trigger → 用户审查或后续 Run ``` -`AutomationCoordinator` 只负责触发、声明和恢复，不直接调用模型。执行仍通过任务和 Runtime -边界完成。 +`AutomationCoordinator` 只负责触发、声明和恢复，不直接调用模型。执行仍通过 Job 和 +Runtime 边界完成，Job 的用户可见结果汇入所属 Task Conversation。 ### 7.2 优先级 @@ -255,7 +270,7 @@ Trigger 1. 用户正在等待的前台对话。 2. 用户手动启动的 Run。 3. 等待批准后恢复的 Run。 -4. 到期定时任务。 +4. 到期 Scheduled Task 的 Job。 5. 目标循环和实验 Run。 6. 心跳回顾、记忆巩固和维护。 @@ -372,38 +387,35 @@ Trigger ## 12. 信息架构 -建议将现有“智能心跳”逐步扩展为“自动化中心”，但保留心跳作为一种计划： +当前阶段保留任务中心并适度完善，不新增独立自动化中心。智能心跳使用自己的菜单入口， +并已在现有模型上实现 Global / 多 Project 范围与唯一配置入口： ```text -自动化中心 -├─ 概览 -│ ├─ 正在运行 -│ ├─ 等待审批 -│ ├─ 需要关注 -│ └─ 最近结果 -├─ 计划 -│ ├─ 定时任务 -│ ├─ 智能心跳 -│ ├─ 目标任务 -│ └─ 实验 -├─ 运行 -│ ├─ 时间线 -│ ├─ 任务与步骤 -│ ├─ 监督记录 -│ ├─ 指标与证据 -│ └─ 成果 -├─ 建议 -│ ├─ 记忆候选 -│ ├─ 后续任务 -│ └─ 学习候选 -└─ 设置 - ├─ 全局预算 - ├─ 后台优先级 - ├─ 通知 - └─ 数据保留 +任务中心 +├─ 需要关注 +├─ 进行中 +├─ 已暂停 +└─ 已结束 + └─ 打开任务自身 + +任务自身 +├─ 消息时间线 +├─ Run、步骤与审批活动 +├─ 监督、指标与证据 +└─ 独立成果 + +智能心跳 +├─ 成长概览 +├─ 待处理建议 +├─ 心跳轨迹 +└─ 心跳计划 + └─ Global / 指定 Project ``` -会话页面增加可折叠“监督”右栏，与任务、上下文和成果并列，或在已有右侧工作栏中新增页签。 +监督统一进入应用级助手工作栏中固定且始终可访问的“监督”栏目，不再保留“独立可折叠右栏” +和“动态新增页签”两种实现。栏目默认跟随当前上下文，用户可以固定到其他 Conversation、 +Task、Job/Run 或实验 Run；详细范围与交互契约见 +[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。 ## 13. 安全与隐私 @@ -429,7 +441,7 @@ Trigger - 实际读取的知识库与记忆分区。 - 实际调用的模型、Token、工具、耗时和成果大小。 - 当前预算和剩余预算。 -- 任务、步骤和子任务状态。 +- Task、Job 和 Subjob 状态。 - Supervisor 评论、证据、严重度和处理结果。 - 评估器版本、指标和证据。 - 产生的候选记忆或学习产物。 @@ -462,15 +474,19 @@ experiment_runs ``` 现有 `schedules`、`schedule_runs`、`heartbeat_configs`、`heartbeat_runs`、 -`heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。迁移顺序应先增加统一只读视图和 -关联字段，再逐步让新计划使用统一模型。 +`heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。Schedule 可渐进绑定一个持续 +Task/Conversation，旧 child-task 字段可兼容映射到 Job/Subjob；心跳数据保持独立，不得 +静默转成 `AutomationPlan` 或顶层 Task。未来分区记忆完成设计前，不新增迁移目标。 ## 16. 分阶段实施 ### 阶段 0：统一术语和可观测性 -- 固定 Plan、Run、Goal、Protocol、Supervisor、Observation、Memory Candidate 等概念。 -- 为现有定时任务、心跳和专家子任务建立统一活动视图。 +- 固定 Task、Conversation、Job、Subjob、Run、Plan、Goal、Protocol、Supervisor、 + Observation、Memory Candidate 等概念。 +- 明确 Task 与 Conversation 一对一，Task Center 只是索引，不复制内容。 +- 为现有 Scheduled Task 和专家 Job 建立统一活动视图。 +- 明确当前心跳保持独立，未来分区记忆尚待设计。 - 补充触发来源、运行版本、预算和读写范围展示。 ### 阶段 1：调度与运行基础 @@ -483,6 +499,7 @@ experiment_runs ### 阶段 2：会话监督与分区记忆 - 上线评论型会话监督。 +- 智能心跳配置支持 Global 或指定一个、多个 Project。 - 增加 Automation 和 Run 记忆分区。 - 建立来源、证据、时态、冲突和晋升流程。 @@ -506,17 +523,23 @@ experiment_runs ## 17. 相关文档 -- [自动任务、目标与调度 PRD](./automation-goals-and-scheduling-prd.md) -- [并行实验工作台 PRD](./parallel-experiments-prd.md) -- [会话监督 PRD](./conversation-supervision-prd.md) -- [分区记忆 PRD](./partitioned-memory-prd.md) -- [持续学习与评估门 PRD](./continuous-learning-prd.md) -- [GoodBuddy 长期助手功能规划](../long-term-assistant-roadmap.md) +- [Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md) +- [Task Center PRD](../prd/task-and-job/task-center-prd.md) +- [Scheduled Task PRD](../prd/task-and-job/scheduled-task-prd.md) +- [Job 与 Subjob PRD](../prd/task-and-job/job-and-subjob-prd.md) +- [智能心跳 PRD](../prd/smart-heartbeat/smart-heartbeat-prd.md) +- [并行实验工作台 PRD](../prd/experiments/parallel-experiments-prd.md) +- [会话监督 PRD](../prd/supervision/conversation-supervision-prd.md) +- [分区记忆 PRD](../prd/memory/partitioned-memory-prd.md) +- [持续学习与评估门 PRD](../prd/learning/continuous-learning-prd.md) +- [GoodBuddy 长期助手功能规划](../roadmap/long-term-assistant-roadmap.md) - [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md) ## 18. 总体验收标准 -- [ ] 心跳、定时、目标和实验使用统一的 Plan 与 Run 术语。 +- [ ] 智能心跳保持独立，不作为 Task 类型；未来分区记忆尚未设计。 +- [ ] Task Center 只索引 Task；每个 Task 只绑定一条 Conversation。 +- [ ] Scheduled Task 的重复触发和并行 Job 不创建新的顶层 Task。 - [ ] 每个自动 Run 都能解释触发原因、目标、范围、预算、状态和结果。 - [ ] Ask 自动化无法调用写工具或产生外部副作用。 - [ ] Execute 自动化不能绕过现有审批、主机执行策略和能力控制。 diff --git a/docs/deepseek-harness-runtime-design.md b/docs/architecture/deepseek-harness-runtime-design.md similarity index 97% rename from docs/deepseek-harness-runtime-design.md rename to docs/architecture/deepseek-harness-runtime-design.md index b8d568d..884f3fb 100644 --- a/docs/deepseek-harness-runtime-design.md +++ b/docs/architecture/deepseek-harness-runtime-design.md @@ -524,12 +524,16 @@ OpenCode、Continue 和 DeepSeek Harness 的后续能力按操作生命周期放 | --- | --- | --- | | Composer 通用行 | 附件、语音、知识范围、专家、Ask/Execute、Runtime 和发送 | Session 监督、后台进度、历史任务管理 | | Composer Runtime 专属行 | 仅对当前消息生效且需要高频选择的 Agent、预设、Prompt/Command 快捷操作 | Subagent 树、后台 Job、Workflow/Hook 生命周期 | -| 右侧助手工作栏的未来“Runtime”页签 | 当前会话的 Runtime 状态、Subagent 层级与取消、后台 Job 队列/进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止和会话监督 | 持久模型、程序路径、默认 Agent/预设配置 | +| 助手工作栏固定“Runtime”栏目 | 用户所选会话或 Run 的 Runtime 状态、Subagent 层级与取消、后台 Job 队列/进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止和会话监督 | 持久模型、程序路径、默认 Agent/预设配置 | | 设置 > Agent Runtime | 持久 Runtime 配置、默认值、插件管理、能力清单和连接诊断 | 某次活动会话的实时控制 | -右侧 Runtime 页签采用统一监督模型，再按当前 Runtime 能力显示 OpenCode、Continue 或 DSH 的具体区块。未支持的能力不渲染空卡片或一排禁用按钮；只有用户需要理解缺口时才显示简短说明。切换 Runtime 或会话时，侧栏必须明确更新归属，不能把上一 Runtime 的 Job/Subagent 状态留在当前会话中。 +Runtime 栏目入口始终存在，并采用统一监督模型；内部再按用户所选目标及其 Runtime 的真实能力 +显示 OpenCode、Continue 或 DSH 的具体区域。未支持能力不渲染空卡片或一排禁用按钮，而是 +在用户需要理解缺口时显示原因和可执行入口。跟随模式切换 Runtime 或会话时必须清理上一归属 +的 Job/Subagent 状态，固定目标则保持不变。完整工作栏契约见 +[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。 -所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、父子任务关系、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。 +所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、Task/Job/Subjob 层级、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。 ## 15. IPC 与共享契约 @@ -767,4 +771,4 @@ GoodBuddy 对该 Runtime 采用内部维护策略： 未采用。Main 无法可靠观察 Cordis 内部 Session、Tool、Usage 和权限 seam，只能得到不完整的外部进程行为。 -当前选择让双层内部控制面保持 GoodBuddy 私有，同时允许 Main 从受管 Store 向固定 Host 注入标准 Cordis 插件；插件扩展面不会取代 GoodBuddy 的可信 Main 控制权。 \ No newline at end of file +当前选择让双层内部控制面保持 GoodBuddy 私有，同时允许 Main 从受管 Store 向固定 Host 注入标准 Cordis 插件；插件扩展面不会取代 GoodBuddy 的可信 Main 控制权。 diff --git a/docs/cross-platform-assistant-product-design.md b/docs/design/cross-platform-assistant-product-design.md similarity index 98% rename from docs/cross-platform-assistant-product-design.md rename to docs/design/cross-platform-assistant-product-design.md index f984298..5c009c0 100644 --- a/docs/cross-platform-assistant-product-design.md +++ b/docs/design/cross-platform-assistant-product-design.md @@ -587,11 +587,15 @@ - 每次调用记录工具、参数摘要、授权方式、结果和时间。 - 超时或取消能够终止请求或子进程。 -### 5.13 任务自动化 +### 5.13 Task 与自动化 + +每个 Task 与唯一 Conversation 一对一绑定；Task Center 只是 Task 的索引，不复制会话 +内容。内部步骤、委派、并行分支和定时触发使用 Job/Subjob，执行尝试使用 Run，它们留在 +所属 Task 中。 #### P1 功能 -- 将多步工具调用保存为任务。 +- 将多步工具调用保存为 Task。 - 执行前展示步骤计划、输入和权限。 - 逐步执行、暂停、取消和人工检查点。 - 失败重试和从安全检查点继续。 @@ -617,6 +621,8 @@ #### 功能项 - 系统通知和应用内通知。 +- 保留 Task Center 作为 Task 入口，显示范围、状态、最近进展和需要关注信息。 +- 普通 Conversation、Job、Run、工具步骤和智能心跳记录不作为顶层 Task。 - 生成完成、任务完成、任务失败和等待确认。 - 未读数量、全部已读和按类别过滤。 - 勿扰模式及通知级别设置。 diff --git a/docs/features/automation-goals-and-scheduling-prd.md b/docs/features/automation-goals-and-scheduling-prd.md deleted file mode 100644 index 09b73ab..0000000 --- a/docs/features/automation-goals-and-scheduling-prd.md +++ /dev/null @@ -1,399 +0,0 @@ -# 自动任务、目标与调度 PRD - -## 文档信息 - -| 项目 | 内容 | -| --- | --- | -| 状态 | 设计中 | -| 版本 | 0.1 | -| 日期 | 2026-08-13 | -| 依赖 | [自动化、监督与记忆平台总体设计](./automation-platform-architecture.md) | - -## 1. 背景 - -GoodBuddy 当前的定时任务支持单次、每日和每周触发固定 Ask 提示，并保存任务和成果； -智能心跳支持每日或每周回顾有界的会话、任务和已确认记忆。两者尚不能表达事件触发、 -目标、成功标准、预算、停止条件和安全恢复。 - -## 2. 产品边界 - -| 类型 | 用户意图 | 是否形成循环 | -| --- | --- | --- | -| 定时任务 | 在指定时间执行已知操作 | 否 | -| 事件任务 | 当明确事件发生时执行已知操作 | 否 | -| 目标任务 | 在预算内持续推进到可验证结果 | 是 | - -智能心跳是特殊的定时观察任务。并行实验属于独立产品。 - -## 3. 已确认的产品决策 - -1. 自动化定义与每次运行分离，编辑计划不改变已启动 Run。 -2. 第一阶段保留现有定时任务的 Ask 限制，Execute 分阶段开放。 -3. Execute 自动化不能因无人值守而绕过现有审批、主机执行策略和工具控制。 -4. 应用退出后不承诺继续运行，重启后只进行状态恢复和错过执行结算。 -5. 目标任务必须有成功标准，以及预算或人工结束条件。 -6. 模型可以提出计划，确定性状态机负责预算、停止、权限和恢复。 -7. 同一计划默认最多一个活动 Run。 -8. 后台任务可被背压延后，不能挤占用户正在等待的前台请求。 -9. 结果未知的外部副作用步骤不自动重试。 -10. 项目、知识库、记忆、目录和工具范围在保存和运行页持续可见。 - -## 4. 目标 - -- 支持单次、每日、每周、每月、工作日和受限 Cron。 -- 支持任务完成、失败、会话完成等内部事件触发。 -- 允许用户用自然语言生成结构化草稿，再检查后启用。 -- 为目标任务建立有界的“观察、计划、行动、评估”循环。 -- 提供幂等、租约、错过执行、取消、重试、恢复、预算和审计。 -- 为后续并行实验和持续学习复用协议、指标和运行基础。 - -## 5. 非目标 - -- 第一阶段不提供任意节点、脚本和循环的通用 DAG 编辑器。 -- 不允许模型编写并执行任意 Shell、SQL 或无限频率 Cron。 -- 不支持应用退出后通过未安装的系统服务继续运行。 -- 不把“模型说完成了”作为唯一成功标准。 -- 不允许自动任务静默修改自身权限、触发器或预算。 -- 不在目标循环中无限创建子任务或专家。 - -## 6. 创建与启用 - -用户可以先输入自然语言意图： - -```text -每周五下午 5 点总结本项目本周完成和失败的任务， -列出下周三个优先事项，不要修改文件。 -``` - -模型只生成草稿： - -- 名称、说明和自动化类型。 -- 触发器。 -- 目标、输出和成功标准建议。 -- 工作模式和 Runtime 建议。 -- 数据范围。 -- 预算、停止条件和通知。 - -草稿不能自动启用。用户必须检查结构化配置。 - -### 6.1 所有计划必填 - -- 名称、范围和类型。 -- 触发器。 -- 工作模式和 Runtime。 -- 输入、输出和通知。 -- 预算和数据保留。 -- 知识库、记忆、目录和工具范围。 - -### 6.2 目标任务额外必填 - -- 目标描述。 -- 至少一个成功标准。 -- 约束。 -- 最大轮数或截止时间。 -- 每轮评估方式。 -- 无进展处理。 - -### 6.3 启用前检查 - -- 时区和下一次运行时间可解析。 -- 项目、目录、Runtime 和模型可用。 -- Ask 没有写入或外部副作用要求。 -- Execute 的工具和审批范围明确。 -- 预算不是无界值。 -- 事件来源存在且已启用。 -- 目标任务存在停止条件。 - -## 7. 触发器 - -### 7.1 时间触发 - -```ts -type TimeTrigger = - | { type: 'once'; at: string; timezone: string } - | { type: 'daily'; localTime: string; timezone: string } - | { - type: 'weekly' - weekdays: number[] - localTime: string - timezone: string - } - | { - type: 'monthly' - day: number | 'last' - localTime: string - timezone: string - } - | { - type: 'cron' - expression: string - timezone: string - } -``` - -受限 Cron 只允许五字段，不支持秒、年份、宏、`L`、`W`、`#` 或供应商扩展。 -Main 负责解析并展示未来五次运行时间，默认最小间隔为 15 分钟。 - -### 7.2 事件触发 - -第二阶段支持： - -- `conversation.completed` -- `task.completed` -- `task.failed` -- `artifact.created` -- `knowledge.sync.completed` -- `magic_note.updated` - -事件触发必须配置来源范围、确定性过滤、去重窗口、冷却时间和并发上限。 -基础匹配不调用模型。 - -### 7.3 手动触发 - -- “立即运行”创建独立 Run，不改变下次计划时间。 -- 多次点击使用调用级幂等键去重。 -- 未保存的变更需先保存为新版本，或明确使用当前已发布版本。 - -### 7.4 错过执行 - -| 策略 | 行为 | -| --- | --- | -| `skip` | 记录跳过，不补跑 | -| `run_once` | 无论错过多少次，只补一次 | -| `catch_up_bounded` | 在数量和时间窗口上限内补跑 | - -有界补跑默认最多 3 次、最多回溯 7 天。补跑同样受并发和预算控制。 - -### 7.5 时区和夏令时 - -- 保存 IANA 时区，不保存固定 UTC 偏移。 -- 春季不存在的本地时间在当日第一个有效分钟运行。 -- 秋季重复时间只运行一次。 -- 系统时区变化不自动修改计划时区。 -- UI 显示计划时区与本机时区差异。 - -## 8. 目标任务 - -### 8.1 目标模型 - -```ts -type AutomationObjective = { - statement: string - successCriteria: SuccessCriterion[] - constraints: Constraint[] - deadline?: string -} - -type SuccessCriterion = - | { type: 'artifact_exists'; kind: string; minimumCount: number } - | { type: 'task_state'; taskId: string; expected: 'completed' } - | { - type: 'metric_threshold' - metric: string - operator: string - value: number - } - | { type: 'checklist'; items: string[] } - | { type: 'human_review' } - | { - type: 'model_rubric' - rubricId: string - minimumScore: number - } -``` - -模型 Rubric 不能是唯一标准，除非任务本质是开放内容评价且 UI 明确标注。 - -### 8.2 有界循环 - -```text -Observe - → Plan next action - → Check permissions and budget - → Act or request approval - → Evaluate progress - → Complete, pause, revise or continue -``` - -每轮持久化观察摘要、下一步、实际任务或工具、成果、指标、预算、进展状态和 -Supervisor 决策。只保存专门生成的结构化理由摘要，不保存隐藏推理。 - -### 8.3 无进展检测 - -出现任一情况进入 `attention_required`： - -- 连续两轮没有指标改善或新成果。 -- 重复提出相同下一步。 -- 连续失败达到上限。 -- 需要的输入或权限不可用。 -- 剩余预算不足。 -- Supervisor 判定目标或前提需要澄清。 - -默认暂停并请求用户选择，不自动扩大范围。 - -### 8.4 计划修订 - -目标任务可以建议修改步骤、缩小目标、请求输入、增加预算或改变 Runtime。 -修改范围、预算、Runtime、工作模式或权限必须用户确认，并形成新版本或 Run 修订记录。 - -## 9. 工作模式与审批 - -### 9.1 Ask - -- 默认只读。 -- 只使用明确开放的只读数据工具。 -- 不写文件、不执行命令、不发送消息、不修改远程数据。 -- 输出进入成果和通知。 - -### 9.2 Execute - -按以下顺序开放： - -1. 有人值守，沿用逐工具审批。 -2. 预批准低风险工具和参数范围。 -3. 经过专项验证的内置无人值守模板。 - -即使预批准，也不能扩大目录和能力。高风险或越界动作进入 `waiting_approval`。 -密码输入、支付、授权、删除、公开发布和生产变更不能预批准。 - -## 10. 预算与背压 - -```ts -type AutomationBudget = { - maximumDurationMs: number - maximumIterations: number - maximumModelCalls: number - maximumInputTokens?: number - maximumOutputTokens?: number - maximumToolCalls: number - maximumChildTasks: number - maximumArtifactBytes: number - maximumConcurrentChildren: number -} -``` - -建议默认值： - -| 类型 | 最长时间 | 模型调用 | 子任务并发 | -| --- | --- | --- | --- | -| 定时 Ask | 5 分钟 | 4 | 1 | -| 心跳回顾 | 5 分钟 | 2 | 0 | -| 目标 Ask | 30 分钟 | 12 | 2 | -| 目标 Execute | 30 分钟 | 12 | 1 | - -前台请求优先。后台使用独立并发池，达到上限时排队。高负载时低优先级心跳和维护任务 -记录为 `deferred`，压力解除后有界恢复，不能一次性释放全部积压。 - -## 11. 重试、恢复与取消 - -| 失败类型 | 行为 | -| --- | --- | -| 瞬时网络或限流 | 指数退避，有界重试 | -| 模型格式错误 | 最多一次结构化修复 | -| 配置或权限错误 | 不重试，等待修复 | -| 无副作用的确定性工具失败 | 按工具策略重试 | -| 结果未知或已有外部副作用 | 不自动重试 | - -应用退出时停止声明新 Run，取消可取消工作，活动 Run 标记为 `interrupted` 并保存安全 -检查点。重启后用户可恢复、复制剩余步骤或放弃；结果未知步骤必须先人工核实。 - -暂停 Plan 只阻止新 Run，不终止当前 Run。取消 Run 必须传播到子任务和 Runtime， -但不能把已发生的外部副作用假装撤销。 - -## 12. 输出与通知 - -输出可保存为文字或文件成果、创建后续任务建议，或仅通知。后续可支持更新指定魔法笔记。 - -通知事件： - -- Run 完成或失败。 -- 等待审批。 -- Supervisor 要求关注。 -- 目标达成。 -- 预算达到 80%。 -- 连续无进展。 - -同一事件不同时显示重复页内横幅和全局通知。 - -## 13. 信息架构 - -计划列表显示名称、类型、范围、启用状态、下次运行、最近 Run、目标状态和需要关注数量。 - -计划详情页签： - -- 概览。 -- 目标与协议。 -- 触发器。 -- 权限与预算。 -- 运行历史。 - -Run 详情展示总览、时间线、任务、审批、监督、指标、证据、成果以及实际读取的知识和记忆。 - -## 14. 数据模型建议 - -```ts -type AutomationPlan = { - id: string - projectId?: string - kind: 'scheduled_task' | 'heartbeat_review' | 'goal_loop' - name: string - description: string - status: 'draft' | 'active' | 'paused' | 'archived' - currentVersion: number - nextRunAt?: string - createdAt: string - updatedAt: string -} - -type AutomationPlanVersion = { - planId: string - version: number - trigger: TriggerPolicy - objective?: AutomationObjective - protocol: ExecutionProtocol - budget: AutomationBudget - approvalPolicy: ApprovalPolicy - supervisorPolicy?: SupervisorPolicy - memoryBinding: MemoryBinding -} -``` - -状态、范围、下次运行、版本和索引字段使用显式列；版本化协议可以使用经过共享 Schema -验证的 JSON。 - -## 15. 安全要求 - -1. 所有输入由共享 Zod Schema 验证。 -2. Main 重新验证项目、目录、Runtime、工具、知识库和记忆分区归属。 -3. Renderer 不可直接声明 Run 完成或批准工具。 -4. 自动化提示、事件、记忆和成果都视为不可信数据。 -5. 事件过滤不执行用户 JavaScript、SQL 或无限复杂表达式。 -6. Cron 有复杂度和最小间隔限制。 -7. 自动化不能读取未绑定知识库、桌面上下文或其他项目记忆。 -8. 日志和通知对私人内容、密钥和工具输出有界脱敏。 - -## 16. 实施顺序 - -1. 统一现有 Schedule 和 Heartbeat 的 Run 视图。 -2. 增加幂等、租约、月度、工作日、受限 Cron、错过执行和未来运行预览。 -3. 建立内部持久事件、过滤、冷却和去重，首期只支持 Ask。 -4. 上线目标 Ask、有界循环、无进展检测和人工暂停。 -5. 接入会话监督。 -6. 再开放有人值守和预批准低风险 Execute。 - -## 17. 验收标准 - -- [ ] 支持单次、每日、每周、每月、工作日和受限 Cron。 -- [ ] UI 显示计划时区和未来五次运行时间。 -- [ ] 夏令时不会造成计划漂移或双跑。 -- [ ] 同一计划同一时间点只产生一个 Run。 -- [ ] 错过执行按配置跳过、补一次或有界补跑。 -- [ ] 手动运行不改变下次计划时间。 -- [ ] Ask 自动化在 Runtime 边界拒绝写工具和外部副作用。 -- [ ] 目标任务必须有成功标准和停止条件。 -- [ ] 每轮都有观察、行动、评估和预算记录。 -- [ ] 连续无进展会暂停，不无限循环。 -- [ ] 达到预算使用 `budget_exceeded`，不伪装为成功。 -- [ ] 设置变化不影响已启动 Run。 -- [ ] 重启后不自动重放结果未知的副作用步骤。 -- [ ] 后台任务排队时不挤占前台模型请求。 diff --git a/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md b/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md new file mode 100644 index 0000000..a40b38a --- /dev/null +++ b/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md @@ -0,0 +1,762 @@ +# 通用助手工作栏与执行空间 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.3 | +| 日期 | 2026-08-19 | +| 适用产品 | GoodBuddy 桌面端 | +| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) | +| 相关能力 | [会话监督](../supervision/conversation-supervision-prd.md)、[自动化平台](../../architecture/automation-platform-architecture.md)、[长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) | + +## 1. 背景 + +GoodBuddy 已经在聊天右侧提供上下文、工作区、浏览器和成果面板，也已经具备 +Runtime 事件、Git 变更、文件预览、成果存储、受控浏览器和专家 Job 等基础能力。后续还 +计划增加： + +- Conversation 和 Task/Job Run 的独立监督。 +- OpenCode、Continue 和 DeepSeek Harness 的 Runtime 生命周期监督。 +- 用户可直接使用的终端和受管进程。 +- HTML 等成果的即时安全预览。 +- 本机与 SSH 远程主机上的工作区和 Agent Runtime。 + +这些能力不能被收束为只面向编程的工作台。监督、Runtime、终端、进程、浏览器、成果和 +上下文都可以服务于普通问答、内容分析、自动化、数据处理、远程运维、知识整理和软件开发。 +同时，能力目录也不能根据当前页面、项目类型或 Runtime 能力无提示地变化，否则用户无法在 +需要时主动打开面板并选择目标、主机或运行环境。 + +本设计把右侧区域定义为应用级的“助手工作栏”，并把本机或远程的目录、终端、进程和 +Runtime 统一抽象为“执行空间”。 + +## 2. 产品定义 + +### 2.1 助手工作栏 + +助手工作栏是 GoodBuddy 中始终可访问的应用级工具容器。它提供稳定能力目录，用户从中 +查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器、成果和 +上下文面板实例。稳定的是能力的可发现性，不是九个同时占据界面的固定面板。 + +工作栏不是： + +- 只在编程项目中出现的 IDE 面板。 +- 当前聊天消息的附属详情框。 +- 根据能力探测结果自动增删入口的动态菜单。 +- 绕过 Main、Preload、Ask/Execute 或审批边界的控制台。 +- 全系统进程管理器、任意文件浏览器或无边界远程管理工具。 + +### 2.2 执行空间 + +执行空间描述工作区、终端、受管进程和 Agent Runtime 实际运行的位置： + +```ts +type ExecutionSpace = + | { + kind: 'local' + rootPath?: string + } + | { + kind: 'ssh' + hostId: string + remoteRootPath?: string + } +``` + +执行空间可以来自当前项目，也可以由用户在工作栏中临时选择。临时选择不会静默修改项目 +设置，只有用户显式保存时才成为项目默认值。 + +## 3. 核心产品原则 + +### 3.1 能力目录稳定，面板实例由用户控制 + +工作栏能力目录提供以下标准能力： + +```text +任务中心 +监督 +Runtime +终端 +进程 +工作区 +浏览器 +成果 +上下文 +``` + +- 应用不得根据当前项目、会话、Runtime、主机或探测结果无提示地增删能力目录项。 +- 用户主动打开、关闭、排序和停靠面板实例；应用不默认同时挂载全部能力。 +- Task Center 是 Task 的单例应用级索引。每个 Task 与唯一 Conversation 一对一；Task + Center 不复制会话内容，也不显示普通 Conversation、Job、Run 或心跳事项。 +- 当前能力、连接、数据和空状态可以动态变化。 +- 能力不可用时，目录项或已打开面板显示原因、影响和可执行的配置或切换入口，不能只通过隐藏表示。 +- 用户可以在设置中调整目录顺序；恢复默认布局恢复标准目录与默认打开面板，不强制打开全部能力。 +- 同一能力需要并排比较不同目标时可以创建多个实例，每个实例拥有独立身份和范围绑定。 + +### 3.2 当前上下文只提供默认值 + +任务中心作为全局索引不跟随当前会话，也不支持为同一列表打开多个目标实例。其他可绑定 +目标的能力使用当前会话、项目、Runtime 和主机帮助新面板实例初始定位，但这些上下文不是 +使用门槛： + +- 监督默认选择当前会话，用户可以改选其他 Conversation、Task、Job/Run 或实验 Run。 +- Runtime 默认跟随当前会话，用户可以固定到其他活动或历史 Run。 +- 终端默认使用当前项目执行空间，用户可以新建本机或远程终端。 +- 工作区默认显示当前项目目录，用户可以打开其他本机目录或远程目录。 +- 成果和上下文默认使用当前范围，用户可以切换到项目、全局或其他允许范围。 + +每个可切换目标的面板实例都提供一致的范围模式： + +```text +跟随当前上下文 +固定到指定对象 +``` + +固定目标失效时，面板显示“目标不可用”和修复入口，不静默回到其他目标。 + +### 3.3 用户控制打开、切换和介入 + +- 后台事件可以更新目录徽标、面板状态和通知，但不得无条件抢占当前面板。 +- 只有用户刚刚发起且明确需要面板完成的交互，才可以打开对应面板。 +- 浏览器画面、审批、监督警告、Runtime 失败和终端退出默认通过徽标或通知提示。 +- 高风险状态必须持续可见，但不以自动切页代替用户选择。 +- 用户切换页面、会话或项目时，已固定的面板目标保持不变；跟随模式才更新目标。 + +### 3.4 入口稳定不等于虚假能力 + +稳定能力目录和已打开面板必须准确呈现能力差异： + +- 当前 Runtime 不支持后台 Job 时，Runtime 能力仍可发现；打开后说明当前可监督的内容。 +- 当前执行空间没有 Git 仓库时，工作区文件功能仍可使用，Git 区域显示不可用原因。 +- 没有活动进程时，进程面板提供创建终端或启动 Runtime 的入口。 +- 没有项目时，终端和工作区允许用户选择本机目录或远程主机。 +- 监督未启用时，监督面板提供目标、模式和“开始监督”，而不是隐藏能力。 + +不得渲染成排没有解释的禁用按钮，也不得把“进程连通”描述为已经支持完整原生监督。 + +### 3.5 通用能力与领域能力分层 + +- 监督判断目标、证据、矛盾、遗漏、质量和风险，不假设目标一定是编程。 +- Runtime 监督展示运行生命周期，不假设 Runtime 一定是 OpenCode。 +- 终端和进程是通用执行能力，不只服务代码构建。 +- 工作区可以是文档、数据、知识或代码目录；Git 是可选区域。 +- HTML 预览属于通用成果能力，不只用于网页开发。 +- SSH 主机可以承载 Agent、自动化、数据处理和工作区，不只代表远程代码仓库。 + +## 4. 目标 + +### 4.1 用户目标 + +- 从任意主要页面随时发现同一组稳定能力，并按需打开所需面板。 +- 自主选择每个可绑定目标的面板实例跟随当前上下文还是固定到指定目标。 +- 在不中断主任务的情况下观察监督意见、Runtime、进程和成果。 +- 随时创建本机或远程终端，并理解其执行位置和权限。 +- 查看 GoodBuddy 管理的进程及其来源、输出和停止状态。 +- 对生成的 HTML、Markdown、JSON、图片等成果进行即时安全预览。 +- 管理 SSH 主机，并在远程执行空间中运行受控 Agent Runtime。 + +### 4.2 产品目标 + +- 建立不依赖具体页面和 Runtime 的应用级工作栏、能力目录和面板实例壳层。 +- 建立统一范围、执行空间、生命周期、成果和控制契约。 +- 复用现有 Project、Conversation、Task、Artifact、Activity 和 Approval 数据。 +- 保持 Renderer 无任意文件、进程、PTY、SSH 或 Electron API 能力。 +- 保持 Ask 只读、Execute 审批、取消、超时、输出边界和活动审计。 +- 为本机与远程能力提供一致 UI，同时准确表达能力差异。 + +## 5. 非目标 + +- 不把 GoodBuddy 改造成完整 IDE。 +- 不提供全系统进程枚举和任意 PID 终止。 +- 不默认扫描用户全部目录、远程主机或 SSH 配置。 +- 不允许 Agent 未经现有 Runtime 边界直接向用户终端注入输入。 +- 不自动执行 HTML 中的脚本或访问网络。 +- 不让监督器自动替用户发言、批准工具、扩大范围或修改安全策略。 +- 不在首期承诺网络断开后远程任务一定可恢复。 +- 不在首期支持任意 ProxyCommand、任意端口转发或 SSH Agent Forwarding。 +- 不要求所有 Runtime 提供相同的 Subagent、Job、Hook 或会话能力。 + +## 6. 信息架构 + +### 6.1 应用级位置 + +助手工作栏位于主窗口右侧，但不归属于聊天页面。聊天、知识、魔法笔记、自动化、活动记录 +等主要页面都可以打开它。各页面可以提供默认范围，不能维护互不相容的右栏副本。 + +```text +┌──────────────┬──────────────────────────────┬────────────────────────┐ +│ 主导航 │ 当前主任务 │ 助手工作栏 │ +│ │ │ │ +│ 会话 / 知识 │ 聊天、文档、自动化或数据视图 │ 稳定能力目录 │ +│ 自动化 / 活动│ │ 用户打开的面板实例 │ +│ 设置 │ │ 各实例范围与执行空间 │ +└──────────────┴──────────────────────────────┴────────────────────────┘ +``` + +### 6.2 能力目录与面板实例 + +能力目录不等于同时打开九个面板。推荐使用工作栏内的纵向能力导航，并在旁边或停靠区域管理 +用户已经打开的面板实例： + +- 每项始终显示稳定图标，并提供可见标签或可持续查看的工具提示。 +- 目录使用与其交互模型匹配的列表、工具栏或菜单语义；单实例切换使用 `tablist`、`tab`、 + `tabpanel`，多实例停靠区使用有名称的区域和明确面板标题。 +- 支持方向键、Home、End、Enter、Space、关闭面板和正确焦点恢复。 +- 徽标显示未解决数量、等待审批或失败状态，并同时提供文字或可访问名称。 +- 用户调整目录顺序、打开实例、停靠位置和尺寸后持久化；关闭实例后能力仍可从目录重新打开。 +- 默认布局只恢复经过产品确认的少量常用面板，不自动打开全部标准能力。 +- 每个实例显示稳定实例 ID、能力名称、跟随或固定状态与当前目标；同能力多实例不能只靠位置区分。 + +当前聊天右栏过渡实现保留 Task Center、上下文、工作区、浏览器和成果五个横向页签时，必须 +单行横向滚动，不能自动隐藏或缩写到不可辨认。Task Center 继续作为 Task 的现有入口； +审批定位到所属 Task、Job 或 Runtime。智能心跳不作为工作栏页签，其报告、建议、历史和完整配置统一归属 +“智能心跳”菜单入口。当前阶段不新增独立自动化中心。 + +### 6.3 工作栏尺寸 + +- 宽窗口：工作栏停靠右侧，支持键盘和指针调整宽度。 +- 中等窗口：可停靠或覆盖主内容，保持用户上次选择。 +- 窄窗口：以全屏或接近全屏抽屉显示。 +- 终端、宽日志和大型成果允许用户切换到底部停靠或独立窗口。 +- 应用只建议适合的布局，不因面板内容自动改变用户已经选择的停靠位置。 + +## 7. 能力与面板定义 + +### 7.1 Task Center + +Task Center 保留为工作栏中的稳定入口，并在现有基础上适度完善： + +- 只索引 Task；每个 Task 与唯一 Conversation 一对一绑定。 +- 显示名称、Global 或 Project 范围、状态、最近进展、真实活动时间和需要关注信息。 +- 点击 Task 直接打开其 Conversation。 +- 完整消息、Job、Run、工具、Subagent、审批和成果分别留在 Task Conversation、Runtime、活动记录和 + 成果查看器中，不在窄栏复制。 +- 智能心跳的报告、建议、历史和配置不进入任务中心。 + +任务中心是单例索引，不使用其他能力的“跟随 / 固定目标”多实例模型。后台状态可以更新 +徽标和排序，但不能自动打开面板或抢占用户当前工作。 + +详细产品边界以 [Task Center PRD](../task-and-job/task-center-prd.md) 和 +[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 为准。 + +### 7.2 监督 + +监督是通用观察与评论入口，详细行为以 +[会话监督 PRD](../supervision/conversation-supervision-prd.md) 为准。 + +监督能力在目录中稳定可发现；用户打开面板实例后可以选择： + +- 普通会话。 +- Task 或 Job/Run。 +- 实验 Run 或实验整体。 +- 后续支持的文档分析和其他可监督对象。 + +监督面板包含： + +- 当前目标与范围。 +- 开启状态、监督模式、触发方式和预算。 +- 评论、警告、人工复核请求和证据。 +- 未解决、已查看、已解决、忽略和误报状态。 +- “带入输入框”“查看证据”“追问”“停止当前回复”等用户介入操作。 + +“采纳”只生成可编辑草稿或显式会话操作，不自动发送、执行、切换 Execute 或批准工具。 + +### 7.3 Runtime + +Runtime 能力统一监督直连模型、OpenCode、Continue、DeepSeek Harness 和后续 Runtime。 +能力在目录中稳定可发现，打开的面板实例依据所选 Runtime 的真实能力显示状态。 + +共同区域： + +- Runtime、模型连接、会话或 Run 身份。 +- 活动请求、状态、耗时、用量和取消。 +- 工具、审批、问题、上下文压缩和错误。 +- 跳转完整活动记录和持久设置。 + +可选区域： + +- Subagent 父子关系和取消。 +- 后台 Job 队列、进度、结果和终止。 +- Todo、Workflow 和 Hook 运行。 +- 原生会话、暂停、恢复、压缩或释放。 + +可选区域不可用时，用一段有操作路径的状态说明替代空卡片。用户可以在面板中切换 Runtime +或目标 Run，不要求先回到聊天 Composer。 + +### 7.4 终端 + +终端面板允许用户主动创建和管理本机或 SSH 终端： + +- 新建、重命名、切换、关闭和重新连接终端。 +- 选择执行空间、工作目录和 Shell。 +- 显示本机或远程主机、目录、Shell 和连接状态。 +- 支持复制、粘贴、搜索、清屏、滚动和调整终端尺寸。 +- 支持将终端切换到右侧、底部或独立窗口。 + +终端属于用户交互表面。Agent 工具调用可以产生独立受管进程和日志，但不能伪装成用户终端， +也不能在没有明确授权的情况下向现有终端发送按键或命令。 + +### 7.5 进程 + +进程面板只展示 GoodBuddy 创建、托管或明确接管的进程： + +- 用户终端 Shell。 +- Runtime Host、Server、Utility 和远程 Helper。 +- Runtime 后台 Job。 +- 用户通过工作栏显式启动的长运行命令。 +- 浏览器或自动化中属于 GoodBuddy 的受管子进程摘要。 + +每项显示： + +- 名称和有界命令摘要。 +- 来源、执行空间、项目或会话归属。 +- 启动时间、状态、退出码和资源摘要。 +- 有界 stdout/stderr 或结构化日志。 +- 正常终止、必要时强制终止和打开关联对象。 + +Renderer 不接收任意系统 PID 控制能力。控制动作引用 Main 签发的受管进程 ID，并由 Main +重新验证所有权、当前状态和允许操作。 + +### 7.6 工作区 + +工作区面板允许用户选择： + +- 当前项目目录。 +- 其他本机目录。 +- 已配置 SSH 主机上的远程目录。 + +面板提供： + +- 有界目录树和文本文件预览。 +- 当前选择、规范化路径和执行空间。 +- 可选 Git 状态、Diff 和仓库信息。 +- 显式打开、下载副本或在终端中打开。 +- HTML 文件的源码与安全预览。 + +本机和远程访问都必须由 Main 或远程 Helper 在对应文件系统上执行路径规范化、相对路径和 +符号链接边界检查。Renderer 只能提交受约束的相对路径和已授权范围 ID。 + +### 7.7 浏览器 + +浏览器能力在目录中稳定可发现，打开面板后允许用户： + +- 创建新的 GoodBuddy 隔离浏览器会话。 +- 选择当前会话或其他受控浏览器会话。 +- 查看状态、当前 URL、有界画面和错误。 +- 进入明确的交互模式或停止会话。 + +没有浏览器会话时显示“新建浏览器会话”，而不是隐藏能力。模型或后台浏览器活动可以更新 +徽标，但不得无条件打开面板或切换用户当前面板。 + +浏览器面板只管理 GoodBuddy 受控浏览器，不表示可以控制用户已安装的浏览器。 + +### 7.8 成果 + +成果面板统一显示全局、项目、Conversation、Task/Job Run 和监督显式产生的独立成果： + +- Markdown、纯文本和 JSON。 +- 图片和图表。 +- HTML 安全预览。 +- 后续的 PDF、Office、表格和其他受支持格式。 + +普通聊天回复只保留在会话消息流中，不自动复制为成果。只有 Runtime 或受管工具显式声明的 +Artifact、自动化和监督生成的独立输出，以及用户手动导入或明确保存的内容进入成果面板。 +升级前已经自动保存的普通对话 Markdown 可以从成果列表中隐藏，但不应通过升级迁移物理 +删除用户数据库内容。 + +用户可以切换范围、搜索、预览、查看来源、导出或打开关联对象。成果必须保留项目、会话、 +Conversation、Run、创建者、MIME、大小、校验值和时间等可用归属。 + +#### HTML 即时预览 + +- Runtime 或受管工具通过显式 Artifact 事件声明成果，不能让 Renderer 猜测任意路径。 +- Main 验证成果属于当前授权执行空间，限制大小、类型和读取范围后再持久化。 +- HTML 使用 `iframe sandbox=""` 和严格 CSP 进行脚本关闭、网络关闭的静态预览。 +- 清理脚本、事件属性、嵌套 frame、object、embed、base、link、meta refresh、表单和活动 URL。 +- 提供“预览 / 源码”切换，并持续标注“静态安全预览，脚本和网络已禁用”。 +- 不使用 `dangerouslySetInnerHTML`，不启用 Electron `webviewTag`。 +- 外部打开是明确的用户操作，并说明外部浏览器可能执行脚本或联网。 + +### 7.9 上下文 + +上下文面板显示用户已选择或系统准备送入下一次模型请求的内容： + +- 附件、图片和文档提取结果。 +- 知识库、引用和检索范围。 +- 已确认记忆。 +- 浏览器、工作区文件和授权目录。 +- Runtime、监督或自动化显式绑定的其他上下文。 + +每项显示来源、范围、大小、发送状态和用途。用户可以预览、移除或清空。固定到历史 Run +时，上下文只读展示不可变快照；跟随当前 Composer 时才允许编辑下一次请求的上下文。 + +## 8. 范围和选择模型 + +### 8.1 通用目标引用 + +各面板实例使用不包含敏感内容的目标引用： + +```ts +type WorkbarCapabilityId = + | 'supervision' + | 'runtime' + | 'terminal' + | 'processes' + | 'workspace' + | 'browser' + | 'results' + | 'context' + +type WorkbarTargetRef = + | { type: 'conversation'; id: string } + | { type: 'run'; id: string } + | { type: 'project'; id: string } + | { type: 'workspace'; id: string } + | { type: 'runtime-session'; id: string } + | { type: 'terminal'; id: string } + | { type: 'managed-process'; id: string } + | { type: 'browser-session'; id: string } + | { type: 'artifact'; id: string } +``` + +Renderer 选择目标后，Main 必须重新验证对象存在、归属范围和当前用户可见性。不能把目标 ID +直接转换为文件、进程或远程控制权限。 + +### 8.2 跟随与固定 + +```ts +type WorkbarScopeBinding = + | { mode: 'follow'; source: 'active-context' } + | { mode: 'pinned'; target: WorkbarTargetRef } + +type WorkbarPanelInstance = { + id: string + capability: WorkbarCapabilityId + binding: WorkbarScopeBinding + dock: 'right' | 'bottom' | 'window' +} +``` + +- 每个面板实例独立保存绑定方式；同一能力的多个实例不能共享可变选择状态。 +- 绑定只包含公开 ID，不包含路径、凭据、Token 或日志。 +- 删除固定目标后保留失效状态，直到用户选择新目标或恢复跟随。 +- 工作栏重新打开、页面切换和窗口重建后恢复用户打开的实例与选择。 + +## 9. 主机管理与远程执行空间 + +### 9.1 设置入口 + +设置中心增加“主机与远程执行”分类，管理： + +- 主机名称、地址、端口和用户名。 +- 认证方式和凭据配置状态。 +- Host Key 算法与 SHA-256 指纹。 +- 连接测试、远程系统和架构。 +- Helper、Runtime 和能力状态。 +- 删除、重新验证或更新 Host Key。 + +主机配置是全局资源。项目或工作栏只引用主机 ID，不能复制凭据。 + +### 9.2 凭据和主机验证 + +- 优先支持系统 SSH Agent 或 OpenSSH 证书。 +- 导入私钥或密码时使用 Electron `safeStorage` 加密。 +- 凭据绑定主机 ID、地址、端口、用户名和认证类型。 +- Renderer 只接收 `credentialConfigured`、来源和错误状态。 +- 首次连接展示 Host Key 算法和 SHA-256 指纹，必须由用户显式接受。 +- Host Key 变化硬失败，并通过独立高风险流程替换。 +- 禁止 `StrictHostKeyChecking=no` 和默认 SSH Agent Forwarding。 +- 命令参数、URL、日志、SQLite 和 IPC 中不得出现私钥或密码。 + +### 9.3 远程 Helper + +远程能力通过版本化 GoodBuddy Helper 提供： + +- 使用 SSH exec 或受控通道启动，不依赖字符串拼接 Shell 命令。 +- 安装到远程用户级受管目录，不要求 root。 +- 上传内容使用固定版本、大小和 SHA-256 校验，临时写入后原子替换。 +- 握手报告协议版本、系统、架构和能力。 +- 在远程执行路径规范化、Git、文件、PTY、进程组和 Runtime 管理。 +- 对事件、日志、文件、帧、超时、并发和总传输量设置上限。 +- 断开或租约过期后终止孤儿进程。 + +首期断线后把活动运行标记为 `interrupted`，撤销短期能力并要求用户重试；在事件序列、租约、 +重放和幂等附加完成前，不宣称可以无损恢复。 + +### 9.4 远程 Runtime + +- Runtime 在远程执行空间内运行，不能让本机 Runtime 对远程路径进行伪本地操作。 +- Main 保持可信控制面，远程 Helper 只接受有范围、有期限的请求。 +- Ask 的只读限制在远程 Helper 和 Runtime 适配层共同强制。 +- Execute 继续经过 Runtime 工具策略、审批、取消、超时和审计。 +- 模型凭据优先留在 Main，通过仅绑定远程回环的 SSH 隧道和请求级代理提供。 +- 不向远程 Runtime 暴露通用本机 MCP、浏览器、文件系统或其他未分配能力。 + +## 10. Runtime 与进程统一生命周期 + +需要新增统一、受限的生命周期模型： + +```ts +type ManagedLifecycleState = + | 'starting' + | 'running' + | 'waiting_approval' + | 'paused' + | 'stopping' + | 'completed' + | 'failed' + | 'cancelled' + | 'interrupted' +``` + +每个 Runtime 会话、Job、终端或受管进程公开： + +- GoodBuddy 受管 ID。 +- 类型、来源和父子关系。 +- 执行空间和范围。 +- 状态、开始与结束时间。 +- 支持的控制动作。 +- 有界进度、用量和日志游标。 + +控制动作按能力声明： + +```ts +type ManagedControl = + | 'cancel' + | 'terminate' + | 'force-terminate' + | 'pause' + | 'resume' + | 'reconnect' + | 'release' +``` + +界面不能因为状态枚举中存在某个动作就假设所有 Runtime 都支持。Main 根据当前受管对象和 +能力重新验证动作。 + +## 11. 数据与契约建议 + +### 11.1 共享 Zod 契约 + +建议新增： + +- `workbar-contracts.ts` +- `managed-process-contracts.ts` +- `terminal-contracts.ts` +- `remote-host-contracts.ts` +- 通用 Artifact Event 和 Preview 契约 +- Runtime Inspector Snapshot 和 Control 契约 + +所有输入严格限制字符串、数组、日志、帧、路径、端口和事件数量。公开快照不得包含： + +- 凭据和认证头。 +- 完整环境变量。 +- 任意本机或远程绝对路径，除非该路径本身是用户当前可见对象。 +- 未经限制的 stdout/stderr、文件或 Runtime 响应。 +- 可直接传给系统 kill、spawn、Shell 或 SSH 的自由参数。 + +### 11.2 持久化 + +建议增加： + +```text +workbar_preferences +remote_hosts +terminal_sessions +managed_processes +runtime_sessions +runtime_jobs +``` + +其中： + +- 工作栏偏好只保存能力目录顺序、面板实例、停靠布局、尺寸和目标引用。 +- 主机表只保存非敏感元数据和加密凭据引用。 +- 活动终端和进程在应用重启时标记为中断，除非对应远程租约可验证恢复。 +- 日志使用有界环形缓冲或分页持久化，不能无限写入 SQLite。 +- Artifact 继续作为成果的权威实体，不把完整成果复制进工作栏状态。 +- 当前 Renderer `localStorage` 活动记录不能作为 Runtime、监督或进程的权威来源。 + +### 11.3 IPC 与 Preload + +Renderer 只通过显式方法访问： + +- 工作栏偏好和目标绑定。 +- 主机 CRUD、测试和 Host Key 确认。 +- 终端创建、输入、调整大小、关闭和有界输出订阅。 +- 受管进程列表、日志和允许的控制动作。 +- Runtime Inspector 快照、事件和允许的控制动作。 +- 工作区、成果、浏览器、监督和上下文的既有或扩展服务。 + +每个 Main Handler 都必须验证可信发送者、Zod 输入、对象归属和当前状态。不得暴露 raw +Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。 + +## 12. 安全边界 + +1. 工作栏能力目录项和面板实例不授予任何能力；权限只由 Main 中的范围和控制契约产生。 +2. Ask 在本机和远程 Runtime 边界保持只读。 +3. Execute 继续经过现有 Runtime 和审批控制，工作栏不能直接放宽。 +4. 用户终端和 Agent 工具执行使用不同身份和事件来源。 +5. 进程面板只控制 GoodBuddy 受管对象，不接受任意 PID。 +6. 本机和远程路径分别在对应文件系统上 canonicalize 并验证符号链接边界。 +7. HTML 默认静态、无脚本、无网络、无 Electron API。 +8. Supervisor 不接收授权回调，不能批准工具或替用户发送消息。 +9. SSH Host Key 必须固定，凭据保留在 Main 加密存储。 +10. 远程端只获得请求级、可撤销、最小范围能力。 +11. 关闭面板或切换目标、主机或 Runtime 时，旧订阅必须取消；其他固定实例的订阅明确保留。 +12. 通知、徽标和日志不得包含密钥、私人正文或未脱敏提供商响应。 + +## 13. 状态、错误和恢复 + +每个面板实例区分： + +- 尚未选择目标。 +- 目标为空。 +- 正在连接或加载。 +- 正常可用。 +- 部分可用。 +- 当前能力不支持。 +- 连接失败。 +- 权限不足或只读。 +- 目标已失效。 +- 操作已取消或中断。 + +错误必须保留用户选择、终端缓冲、输入草稿、范围和可重试上下文。短期成功和非局部错误使用 +应用通知；预览失败、终端断线、Host Key 变化、监督证据失效等需要本地恢复的错误留在面板 +内。同一事件不得同时重复显示为面板警告和应用通知。 + +## 14. 性能与资源边界 + +- 工作栏关闭或面板实例关闭时停止对应非必要画面和高频日志推送，但保留 Main 中的受管运行。 +- 每个打开的面板实例只订阅其跟随或固定目标，不进行全局无界监听。 +- 终端和日志使用增量序号、环形缓冲和背压。 +- HTML、文件、目录、浏览器画面和远程传输沿用或收紧现有大小限制。 +- Runtime Snapshot 与事件流分离，重新打开时先取权威快照，再接增量事件。 +- 监督使用独立低优先级并发池和预算，不延迟前台回答。 +- 应用退出时停止新操作，取消订阅，关闭终端、隧道和 Helper，并在期限内标记未完成对象。 + +## 15. 无障碍与响应式 + +- 能力目录、所有面板实例、目标选择器、终端控制和进程操作可用键盘完成。 +- 能力目录与面板标题具有稳定可访问名称，徽标不是唯一状态信号。 +- 终端需要独立可访问说明，并允许关闭动画和声音提示。 +- 进程和 Runtime 高频日志不逐行进入实时区域，只播报重要状态变化。 +- 监督证据定位后将焦点移动到对应对象，并提供返回监督记录的方式。 +- HTML iframe 有明确标题、静态安全说明和源码替代视图。 +- 窄窗口下能力目录仍完整可达，不因空间不足隐藏能力。 +- 文字缩放到 200% 时，当前目标、执行空间、风险状态和停止操作不能被裁切。 + +## 16. 分阶段实施 + +### 阶段 0：应用级工作栏壳层 + +- 将当前聊天专属右栏提升为应用级壳层。 +- 建立稳定能力目录和用户打开、关闭、排序、停靠的面板实例模型。 +- 建立实例级跟随、固定和失效目标语义。 +- 保留现有任务中心、上下文、工作区、浏览器和成果行为。 +- 将 Task Center 明确为 Task 的单例索引，并补齐范围、状态、最近进展、需要关注和直接打开 Conversation。 +- 审批在所属任务或 Runtime 中持续可见，不新增独立审批面板。 +- 智能心跳菜单入口承接完整配置和范围后，再从任务中心移除重复表单；不得移除任务中心本身。 + +### 阶段 1：成果与 Runtime 可观测性 + +- 通用 Artifact Event。 +- HTML 工作区和成果的静态即时预览。 +- Runtime Inspector Snapshot 与事件。 +- OpenCode 会话、子会话、Todo、工具、用量和取消。 +- 直连模型及现有 GoodBuddy Subagent 的统一展示。 + +### 阶段 2：监督、终端与受管进程 + +- 普通会话手动监督和右栏评论流。 +- 本机 PTY 终端。 +- 受管进程注册、日志和终止。 +- 自动回复后监督、节流和独立预算。 +- 用户选择终端停靠位置。 + +### 阶段 3：Runtime 原生长期能力 + +- Continue 会话级 Host。 +- Continue Background Job、Subagent 和 Hook 的有界适配。 +- DeepSeek Harness 后续服务的能力握手。 +- Runtime Job、Workflow 和会话恢复契约。 + +### 阶段 4：SSH 主机与远程执行空间 + +- 主机管理、加密凭据和 Host Key 固定。 +- Linux x64/arm64 Helper 安装与握手。 +- 远程工作区、Git、终端和受管进程。 +- 远程 Runtime 执行、取消、超时和审计。 +- 首期断线明确标记中断，不承诺恢复。 + +### 阶段 5：恢复与扩展 + +- 远程租约、事件重放和幂等重连。 +- 更多远程系统和架构。 +- PDF、Office 和数据成果预览。 +- Conversation、Task/Job Run 和实验的完整监督。 +- 用户可导入导出工作栏布局和主机非敏感配置。 + +## 17. 验收标准 + +### 17.1 稳定能力目录与用户控制 + +- [ ] 九个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。 +- [ ] Task Center 继续作为 Task 的单例索引，不删除入口、不复制会话，也不混入 Job、Run 或心跳事项。 +- [ ] 项目、会话、Runtime 或主机变化不会无提示地增删能力目录项。 +- [ ] 用户可以按需打开、关闭、排序和停靠面板实例。 +- [ ] 用户可以独立设置每个可绑定目标的面板实例跟随或固定目标，并为同一能力打开多个目标实例。 +- [ ] 固定目标失效后显示修复状态，不静默切换。 +- [ ] 后台事件不会无条件打开面板或抢占用户当前实例。 +- [ ] 用户可一键恢复标准能力目录和默认的少量打开面板。 + +### 17.2 通用使用 + +- [ ] 没有项目时仍可创建终端、选择工作区、打开浏览器和查看成果。 +- [ ] 监督可以作用于普通 Conversation、Task、Job/Run 和后续实验对象，不假设编程语境。 +- [ ] 工作区不是 Git 仓库时仍可浏览文件。 +- [ ] Runtime 不支持某项原生能力时仍可从目录打开面板并获得准确说明。 + +### 17.3 安全与控制 + +- [ ] Renderer 没有任意文件、Shell、进程、PTY、SSH 或 Electron API。 +- [ ] Agent 不能未经授权向用户终端注入命令。 +- [ ] 进程面板不能枚举或终止任意系统进程。 +- [ ] Ask 在本机和远程执行空间均无法调用写入或外部副作用工具。 +- [ ] HTML 预览无法执行脚本、联网、打开窗口、提交表单或访问 Electron API。 +- [ ] Supervisor 不能自动发送消息、批准工具、切换工作模式或扩大范围。 +- [ ] SSH 首次连接和 Host Key 变化均经过明确验证流程。 +- [ ] 凭据不进入 Renderer、日志、SQLite 明文或命令参数。 + +### 17.4 生命周期与恢复 + +- [ ] Runtime、终端、Job 和进程具有权威 Main 快照和有序增量事件。 +- [ ] 取消、终止、失败、断线和应用退出都有确定终态。 +- [ ] 切换跟随目标后不显示上一对象的过期状态。 +- [ ] 固定目标的订阅在页面切换后保持，关闭时正确释放。 +- [ ] 日志、终端、文件、成果和远程传输均有明确上限和背压。 + +### 17.5 可用性 + +- [ ] 宽、中、窄窗口均可访问完整能力目录和用户打开的面板实例。 +- [ ] 仅使用键盘可以选择能力、面板实例、目标、执行空间和控制动作。 +- [ ] 状态不只依赖颜色，徽标具有文字或可访问名称。 +- [ ] 终端、HTML、监督证据和高频日志具有可访问替代或降噪行为。 + +## 18. 相关文档的职责 + +- 本文是助手工作栏稳定能力目录、用户面板实例、范围控制和执行空间的产品总契约。 +- [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 定义 Task、Conversation、 + Job、Subjob、Run 与 Subagent。 +- [Task Center PRD](../task-and-job/task-center-prd.md) 定义应用级 Task 索引。 +- [智能心跳 PRD](../smart-heartbeat/smart-heartbeat-prd.md) 定义心跳入口、范围和长期边界。 +- [会话监督 PRD](../supervision/conversation-supervision-prd.md) 定义监督判断、证据、预算和介入边界。 +- [自动化平台总体设计](../../architecture/automation-platform-architecture.md) 定义 Plan、Job、Run、监督、预算和记忆。 +- [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) 记录整体长期能力与实施背景。 +- [DeepSeek Harness Runtime 设计](../../architecture/deepseek-harness-runtime-design.md) 定义该 Runtime 的具体适配边界。 +- [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。 + +若其他文档把工作栏描述为九个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口， +或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供 +默认值”的产品决策为准。 diff --git a/docs/features/wechat-clawbot-channel-project-prd.md b/docs/prd/channels/wechat-clawbot-channel-project-prd.md similarity index 100% rename from docs/features/wechat-clawbot-channel-project-prd.md rename to docs/prd/channels/wechat-clawbot-channel-project-prd.md diff --git a/docs/features/doc-extract.md b/docs/prd/document-processing/document-extraction-and-local-ocr.md similarity index 100% rename from docs/features/doc-extract.md rename to docs/prd/document-processing/document-extraction-and-local-ocr.md diff --git a/docs/features/parallel-experiments-prd.md b/docs/prd/experiments/parallel-experiments-prd.md similarity index 98% rename from docs/features/parallel-experiments-prd.md rename to docs/prd/experiments/parallel-experiments-prd.md index 922f8ef..6694665 100644 --- a/docs/features/parallel-experiments-prd.md +++ b/docs/prd/experiments/parallel-experiments-prd.md @@ -7,7 +7,7 @@ | 状态 | 设计中 | | 版本 | 0.1 | | 日期 | 2026-08-13 | -| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md)、[自动任务与目标 PRD](./automation-goals-and-scheduling-prd.md) | +| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) | ## 1. 背景 @@ -158,7 +158,7 @@ Token 和耗时范围，以及最大并发。超过上限时要求缩小变量 - `experimentRunId` 和运行会话。 - 变量快照和临时上下文。 - Run 记忆分区。 -- 任务、子任务和成果。 +- Task、Job、Subjob 和成果。 - 指标、证据和 Runtime 会话标识。 禁止： diff --git a/docs/features/knowledge-rag-enhancement-prd.md b/docs/prd/knowledge/knowledge-rag-enhancement-prd.md similarity index 100% rename from docs/features/knowledge-rag-enhancement-prd.md rename to docs/prd/knowledge/knowledge-rag-enhancement-prd.md diff --git a/docs/features/knowledge-rag-enhancement-user-stories.md b/docs/prd/knowledge/knowledge-rag-enhancement-user-stories.md similarity index 99% rename from docs/features/knowledge-rag-enhancement-user-stories.md rename to docs/prd/knowledge/knowledge-rag-enhancement-user-stories.md index 9cbd637..edcb155 100644 --- a/docs/features/knowledge-rag-enhancement-user-stories.md +++ b/docs/prd/knowledge/knowledge-rag-enhancement-user-stories.md @@ -7,7 +7,7 @@ | 状态 | 实施中 | | 版本 | 0.1 | | 日期 | 2026-08-11 | -| 关联 PRD | [知识库检索与分块增强 PRD](knowledge-rag-enhancement-prd.md) | +| 关联 PRD | [知识库检索与分块增强 PRD](./knowledge-rag-enhancement-prd.md) | ## 1. 角色 diff --git a/docs/features/continuous-learning-prd.md b/docs/prd/learning/continuous-learning-prd.md similarity index 93% rename from docs/features/continuous-learning-prd.md rename to docs/prd/learning/continuous-learning-prd.md index e3647c6..0216d4e 100644 --- a/docs/features/continuous-learning-prd.md +++ b/docs/prd/learning/continuous-learning-prd.md @@ -5,13 +5,14 @@ | 项目 | 内容 | | --- | --- | | 状态 | 设计中，远期能力 | -| 版本 | 0.1 | -| 日期 | 2026-08-13 | -| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md)、[并行实验 PRD](./parallel-experiments-prd.md)、[分区记忆 PRD](./partitioned-memory-prd.md) | +| 版本 | 0.3 | +| 日期 | 2026-08-19 | +| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../experiments/parallel-experiments-prd.md)、[分区记忆 PRD](../memory/partitioned-memory-prd.md) | ## 1. 背景 -智能心跳已经可以生成摘要、后续任务和记忆候选，但这还不是完整学习： +智能心跳可以生成摘要、后续任务和记忆候选，但这还不是完整学习。其长期“未来分区记忆” +方向尚未设计，也不承担持续学习、模式挖掘或自动改进： - 候选是否改善未来行为没有评估。 - 一条反思是否会被检索和使用并不确定。 @@ -82,8 +83,8 @@ Observe ## 5. 候选来源 - 用户对回答、任务或 Supervisor 意见的显式反馈。 -- 智能心跳提出的重复模式。 -- 自动化 Run 的成功与失败比较。 +- 用户对心跳报告或建议的显式反馈。 +- Task/Job Run 的成功与失败比较。 - 并行实验结论。 - 回放评估发现的稳定差异。 - 用户手动创建。 @@ -301,7 +302,8 @@ Shadow 达到配置的最小观察数且无安全退化后进入 `awaiting_appro ## 14. 信息架构 -建议在自动化中心增加“学习”： +若远期验证确有集中学习管理需求，应提供独立且可审计的“学习”视图，而不是放入智能心跳、 +任务中心或一个尚未确认的自动化中心： 1. **候选**：来源、作用域、预期收益和风险。 2. **评估中**：进度、案例和预算。 diff --git a/docs/features/partitioned-memory-prd.md b/docs/prd/memory/partitioned-memory-prd.md similarity index 89% rename from docs/features/partitioned-memory-prd.md rename to docs/prd/memory/partitioned-memory-prd.md index e14dbd5..e9a9c7f 100644 --- a/docs/features/partitioned-memory-prd.md +++ b/docs/prd/memory/partitioned-memory-prd.md @@ -5,9 +5,9 @@ | 项目 | 内容 | | --- | --- | | 状态 | 设计中 | -| 版本 | 0.1 | -| 日期 | 2026-08-13 | -| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md) | +| 版本 | 0.3 | +| 日期 | 2026-08-19 | +| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[智能心跳 PRD](../smart-heartbeat/smart-heartbeat-prd.md)、[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) | ## 1. 背景 @@ -16,13 +16,13 @@ GoodBuddy 当前记忆已经支持： - `global`、`project`、`conversation` 三种作用域。 - `preference`、`fact`、`summary`、`procedure` 四种类型。 - `proposed`、`confirmed`、`rejected` 三种状态。 -- 智能心跳提出 Global 或 Project 记忆候选，由用户确认。 +- 智能心跳提出 Global 或 Project 记忆候选，由用户确认；其长期“未来分区记忆”方向尚未设计。 但当前能力仍不足以支撑自动化和并行实验： 1. 交互请求会把已加载列表中的最多 20 条已确认记忆直接拼入提示，缺少查询相关度和明确的 会话级过滤契约。 -2. 数据库有会话作用域，但心跳只提出 Global 和 Project 记忆。 +2. 数据库有会话作用域，但旧版心跳候选与未来唤起需求混在同一产品概念中。 3. 缺少 Automation、Experiment 和 Run 分区。 4. 来源字段存在于表结构，但普通创建和心跳候选尚未完整保存来源关系。 5. 缺少事实的有效时间、冲突、替代、访问记录和衰减。 @@ -64,6 +64,11 @@ SQLite 显式字段、FTS、来源关系和可选本地 Embedding 足以支持 - 同一实体跨大量会话的别名消歧。 - 可解释的关系证据链。 +### 2.5 未来分区记忆尚待设计 + +已确认智能心跳的长期方向是“未来分区记忆”，但当前尚未定义其数据结构、唤起条件、状态、 +生命周期、与长期记忆的关系或迁移方式。本 PRD 不新增 `FutureMemory` 类型、表或检索规则。 + ## 3. 目标 - 为会话、自动化和并行 Run 提供严格隔离。 @@ -73,6 +78,7 @@ SQLite 显式字段、FTS、来源关系和可选本地 Embedding 足以支持 - 让候选记忆经过确认或评估后再晋升。 - 支持编辑、移动、合并、拒绝、归档、删除和要求忘记。 - 记录哪些 Run 实际读取了哪些记忆。 +- 为现有智能心跳配置建立 Global 或指定 Project 范围，并保持当前候选记忆流程。 ## 4. 非目标 @@ -134,7 +140,7 @@ agent:{expertId} Conversation → Project → Global ``` -自动化 Run： +Task/Job Run： ```text Run → Automation → Conversation（可选）→ Project → Global @@ -224,12 +230,12 @@ type MemorySource = 候选来源： -- 智能心跳。 - 用户明确“记住这个”。 - 会话结束总结。 -- 自动化 Run 结束反思。 +- Task/Job Run 结束反思。 - 实验结论。 - Supervisor 建议后用户采纳。 +- 智能心跳。 候选生成必须： @@ -424,6 +430,9 @@ Project 记忆与 Global 偏好冲突时： 每条记忆展示内容、类型、范围、来源、状态、时间、置信度、重要性和冲突。 +智能心跳的完整配置仍在“智能心跳”菜单中管理；未来分区记忆完成独立设计前，不加入记忆 +中心信息架构。 + ## 16. 数据模型建议 建议表： @@ -459,17 +468,20 @@ Project 记忆与 Global 偏好冲突时： 1. 修正当前交互请求的范围过滤，确保只读 Global、当前 Project 和当前 Conversation。 2. 增加来源记录和“实际进入上下文”的诊断。 -3. 建立 Automation 和 Run Namespace。 -4. 上线有界相关检索，替换简单列表前 20 条拼接。 -5. 增加冲突、时态、替代和归档。 -6. 增加实验冻结快照与 Run 隔离。 -7. 增加可选本地 Embedding 和混合排序。 -8. 只有明确需求后再评估时间知识图谱。 +3. 为现有智能心跳配置增加 Global 或指定 Project 范围，保持候选记忆行为不变。 +4. 建立 Automation 和 Run Namespace。 +5. 上线有界相关检索，替换简单列表前 20 条拼接。 +6. 增加冲突、时态、替代和归档。 +7. 增加实验冻结快照与 Run 隔离。 +8. 增加可选本地 Embedding 和混合排序。 +9. 未来分区记忆和时间知识图谱都必须在明确需求与独立设计后再实施。 ## 19. 验收标准 - [ ] 普通会话只读取 Global、当前 Project 和当前 Conversation 的允许记忆。 -- [ ] 自动化 Run 只读取运行快照绑定的分区。 +- [ ] 智能心跳配置只能属于 Global 或 Main 已验证的一个、多个 Project。 +- [ ] 未来分区记忆完成独立设计前，不新增相关表、状态或检索行为。 +- [ ] Task/Job Run 只读取运行快照绑定的分区。 - [ ] 实验 Run 不能读取其他 Run 的消息或记忆。 - [ ] 每条非手动记忆都有可追溯来源。 - [ ] 候选和被拒绝记忆不进入普通上下文。 diff --git a/docs/prd/smart-heartbeat/smart-heartbeat-prd.md b/docs/prd/smart-heartbeat/smart-heartbeat-prd.md new file mode 100644 index 0000000..68c5809 --- /dev/null +++ b/docs/prd/smart-heartbeat/smart-heartbeat-prd.md @@ -0,0 +1,244 @@ +# 智能心跳 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 入口与范围已实现；未来分区记忆待独立设计 | +| 版本 | 0.5 | +| 日期 | 2026-08-19 | +| 适用产品 | GoodBuddy 桌面端 | +| 文档角色 | 智能心跳当前能力、权威入口、范围和长期边界 | +| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) | +| 相关架构 | [自动化、监督与记忆平台总体设计](../../architecture/automation-platform-architecture.md) | +| 相关界面 | [通用助手工作栏与执行空间 PRD](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) | +| Task 模型 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) | + +> 本文区分近期实施与长期方向。未完成设计的“未来分区记忆”不得转写为数据结构、状态机、 +> 页面、迁移或验收条件。 + +## 1. 已确认的产品边界 + +### 1.1 智能心跳是独立能力 + +- “智能心跳”菜单入口是心跳配置、报告、建议和运行历史的权威位置。 +- 任务中心和设置中心不复制完整心跳配置表单。 +- 智能心跳不并入通用自动化中心，也不作为任务中心条目。 +- 现有心跳报告、记忆建议、行动建议和审计历史在本轮继续保留。 + +### 1.2 长期方向：未来分区记忆 + +已确认的方向只有： + +> 智能心跳未来应成为按范围隔离的未来记忆。 + +以下内容尚未设计： + +- “未来记忆”的数据结构与存储方式。 +- 与当前长期记忆、心跳报告和建议的关系。 +- 唤起条件、状态和生命周期。 +- 到期后的页面和交互。 +- 是否以及如何创建 Task。 +- 旧版心跳数据如何迁移。 + +本轮不得实现 `FutureMemory`、新增未来记忆数据库表，或制作“未来记忆 / 即将唤起 / +已唤起”等页面。后续需要独立 PRD 和用户确认。 + +## 2. 本轮实施范围 + +### 2.1 目标 + +1. 完整心跳配置统一到“智能心跳”菜单入口。 +2. 心跳配置支持 `Global` 或指定一个、多个 Project。 +3. 保留现有概览、待处理建议、运行历史和报告能力。 +4. 新入口完整可用后，再移除任务中心和设置中心中的重复心跳配置。 +5. 旧心跳配置、运行、报告、建议、记忆和任务数据不丢失。 + +### 2.2 非目标 + +- 不设计或实现未来分区记忆。 +- 不修改 Task、Job 或 Task Center 模型。 +- 不新增独立 Automation Center。 +- 不移除定时任务现有入口。 +- 不扩大智能心跳的工具、目录、网络或 Execute 权限。 +- 不让智能心跳跨越配置范围读取数据。 +- 不将现有心跳建议静默转换成 Task。 + +## 3. 智能心跳范围 + +### 3.1 范围选择 + +每条心跳配置必须明确选择： + +| 范围 | 当前执行语义 | +| --- | --- | +| `Global` | 回顾所有 Project 中允许读取的有界会话和任务，并读取 Global 已确认记忆 | +| 指定 Project | 只回顾选中 Project 的有界会话和任务，并读取 Global 与选中 Project 的已确认记忆 | + +指定 Project 可以选择一个或多个项目： + +```text +范围 +(•) Global +( ) 指定项目 + [✓] 网站重构 + [ ] 内容运营 + [✓] 客户研究 +``` + +- `Global` 与指定 Project 互斥。 +- 指定 Project 时至少选择一个项目。 +- 多项目使用 Checkbox，不使用 Switch。 +- 当前项目只可以作为创建表单的建议默认值，不能在保存时隐式覆盖用户选择。 +- 切换当前项目不会改变已经保存的心跳范围。 +- Main 必须重新验证所有 Project ID，Renderer 不能扩大范围。 + +### 3.2 多项目执行 + +多项目配置的一次心跳仍然是一次运行和一份报告： + +- 将选中项目中允许读取的会话、任务和记忆汇总后，再执行现有全局输入上限。 +- 不为每个 Project 分别创建 Run、报告、建议或 Task 副本。 +- 心跳报告成果以无项目归属保存，并在成果元数据中冻结本次配置范围。 +- 心跳产生的项目级记忆建议或行动建议必须明确目标 Project。 +- 目标 Project 不明确时，只能生成 Global 记忆建议或不绑定项目的行动建议，不能猜测。 + +### 3.3 兼容现有配置 + +旧配置按现有 `projectId` 非破坏映射： + +- `projectId` 为空的配置迁移为 `Global`。 +- `projectId` 有值的配置迁移为“指定 Project”，且只绑定原项目。 +- 迁移不修改启停状态、重复规则、时间、回顾窗口、保留期限、下次运行或历史。 +- 项目删除时，只有该项目的配置按现有规则删除；多项目配置移除被删除项目并保留其他范围。 + +## 4. 权威入口 + +| 操作 | 权威入口 | 其他位置 | +| --- | --- | --- | +| 创建或编辑心跳配置 | 智能心跳 > 心跳计划 | 不复制表单 | +| 选择 Global / Project 范围 | 智能心跳 > 心跳计划 | 不依赖当前项目推断 | +| 暂停、恢复、立即心跳或删除 | 智能心跳 > 心跳计划 | 不复制操作 | +| 查看报告与待处理建议 | 智能心跳 | 主导航徽标和通知可触达 | +| 查看运行历史和失败 | 智能心跳 > 心跳轨迹 | 活动记录仅作审计补充 | +| 管理平台级默认值 | 设置中心 | 不显示单条计划 CRUD | + +移除重复入口的顺序： + +1. 先在智能心跳中支持完整创建、编辑、范围、暂停、恢复、立即运行和删除。 +2. 验证旧数据与新范围均可管理。 +3. 再从任务中心移除 `HeartbeatSettings`。 +4. 再从设置中心移除重复 `HeartbeatSettings`，必要时保留“打开智能心跳”链接。 +5. 任一步失败都不得造成用户没有可用配置入口。 + +## 5. 智能心跳页面 + +保留现有四个页面： + +- **成长概览**：状态、成功率、记忆、洞察和行动统计。 +- **待处理建议**：记忆建议和行动建议。 +- **心跳轨迹**：报告与 Run 审计。 +- **心跳计划**：唯一完整配置入口。 + +### 5.1 心跳计划 + +创建和编辑至少显示： + +- 名称。 +- `Global` 或指定 Project 范围。 +- 每日或每周重复规则。 +- 本地时间、星期与 IANA 时区。 +- 回顾窗口。 +- 保留期限。 +- 启停状态。 +- 下次运行与上次状态。 + +交互要求： + +- 使用持久标签，不以 placeholder 代替。 +- 编辑进入明确状态，支持保存或放弃。 +- 保存失败保留草稿。 +- 删除继续使用共享破坏性确认。 +- 运行中禁用重复操作。 +- 保存成功后由计划列表直接反映结果；失败保留草稿并在编辑区就地提示。 + +### 5.2 范围呈现 + +- 页面标题不再根据当前 Project 伪装成心跳实际范围。 +- 每张计划卡片显示 `Global` 或完整 Project 摘要。 +- 多项目过多时显示“项目 A、项目 B 等 N 个”，并提供完整可访问名称。 +- 报告成果元数据保存配置冻结范围；计划卡片始终显示计划自身范围，不根据当前项目重新解释。 +- 项目失效或删除后，界面准确显示剩余范围或配置已被移除。 + +### 5.3 响应式与无障碍 + +- 宽窗口使用 `dashboard` 壳层，创建和编辑区域保持单列。 +- 窄窗口下计划列表和表单转为单列卡片。 +- `Global / 指定项目` 使用共享分段选择控件，Project 多选使用 Checkbox。 +- 范围、状态和失败不能只依赖颜色。 +- 表单错误与字段程序化关联。 +- 对话框或编辑区关闭后，焦点返回触发按钮。 + +## 6. 数据与安全要求 + +目标合同只扩展现有心跳范围，不引入 Future Memory： + +```ts +type HeartbeatScope = + | { kind: 'global' } + | { kind: 'projects'; projectIds: string[] } +``` + +- 旧 `projectId` 只用于迁移兼容，不继续作为目标范围合同。 +- Main 在创建、编辑、列出和执行时验证 Project 归属。 +- Global 读取所有 Project 的有界会话和任务，但长期记忆仍只读取 Global。 +- 指定 Project 读取选中项目的有界会话和任务，以及 Global 与选中项目记忆。 +- 现有输入条数、字符预算、输出大小、超时、重试、租约和工具禁用边界继续生效。 +- 多项目汇总后统一应用上限，不能按项目倍增预算。 +- 心跳结果默认不在系统通知中暴露私人正文。 +- 数据迁移必须使用 SQLite 事务，保留外键、级联删除和现有历史。 + +## 7. 实施状态与后续顺序 + +### 已完成：入口和范围 + +- 扩展共享 Schema、Preload 与 Main 数据合同。 +- 增加 Global / 多 Project 持久化与旧数据迁移。 +- 让心跳执行按冻结范围构建有界输入。 +- 在“心跳计划”中完成创建、编辑和全部计划操作。 +- 补齐范围、迁移、权限和界面测试。 + +### 已完成：移除重复配置 + +- 从 Task Center 移除心跳完整表单，保留 Task 和 Scheduled Task 现有行为。 +- 从设置中心移除单条心跳 CRUD。 +- 如需要，设置中心仅保留“打开智能心跳”导航。 +- 验证应用内仍只有一个完整配置入口。 + +### 后续：独立设计 + +- 未来分区记忆。 +- 与长期记忆的关系。 +- 唤起模型与生命周期。 +- 与 Task 的关系。 + +这些内容需要新的 PRD 和明确确认，不属于本轮实现。 + +## 8. 验收状态 + +- [x] 智能心跳菜单是完整配置的唯一权威入口。 +- [x] 用户可以创建和编辑 `Global` 心跳。 +- [x] 用户可以创建和编辑绑定一个或多个 Project 的心跳。 +- [x] 切换当前 Project 不会改变已保存范围。 +- [x] Main 拒绝不存在、已归档或超出配置范围的 Project ID。 +- [x] Global 与多项目输入遵守现有总上限，不按项目倍增。 +- [x] 多项目一次运行只产生一份 Run 和报告。 +- [x] 旧 Global 和单 Project 配置无损迁移。 +- [x] 旧运行、报告、建议、记忆和任务仍可查看。 +- [x] 心跳计划支持创建、编辑、暂停、恢复、立即运行和删除。 +- [x] 任务中心不再包含完整心跳配置表单。 +- [x] 设置中心不再包含单条心跳 CRUD。 +- [x] 任务中心本身以及定时任务现有行为没有被删除。 +- [x] 智能心跳仍保持只读、禁用工具和有界输入输出。 +- [x] 没有新增 Future Memory 表、状态机或未确认页面。 +- [x] 加载失败、空状态、字段错误和危险操作满足统一设计与无障碍要求。 diff --git a/docs/features/conversation-supervision-prd.md b/docs/prd/supervision/conversation-supervision-prd.md similarity index 89% rename from docs/features/conversation-supervision-prd.md rename to docs/prd/supervision/conversation-supervision-prd.md index f5e3478..ec86c15 100644 --- a/docs/features/conversation-supervision-prd.md +++ b/docs/prd/supervision/conversation-supervision-prd.md @@ -5,9 +5,10 @@ | 项目 | 内容 | | --- | --- | | 状态 | 设计中 | -| 版本 | 0.1 | -| 日期 | 2026-08-13 | -| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md) | +| 版本 | 0.2 | +| 日期 | 2026-08-18 | +| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) | +| 界面归属 | [通用助手工作栏与执行空间](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) | | 体验参考 | GoodBuddy 魔法笔记 AI 评论流 | ## 1. 背景 @@ -27,8 +28,9 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写 ## 2. 产品定义 -会话监督是在明确范围和策略下，对 Conversation、Task、AutomationRun 或 ExperimentRun -的可见事件进行独立观察，产生带证据的评论、告警和人工介入请求。 +会话监督是在明确范围和策略下，对普通 Conversation、Task、Job/Run 或 ExperimentRun +的可见事件进行独立观察，产生带证据的评论、告警和人工介入请求。一个 Task 与唯一 +Conversation 一对一绑定；Job/Run 是内部执行和审计对象。 它不是： @@ -53,7 +55,7 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写 ## 4. 已确认的产品决策 -1. 监督默认关闭，由用户对会话、任务、自动化或实验显式启用。 +1. 监督默认关闭，由用户对 Conversation、Task、Job/Run 或实验显式启用。 2. 监督只读取用户可查看的消息、工具事件、状态、指标、成果摘要和目标。 3. 不读取、推断或保存模型隐藏推理链。 4. 每条重要判断必须引用具体消息、工具、步骤、指标或成果。 @@ -72,7 +74,7 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写 - 及时发现目标偏移、缺少证据、相互矛盾、重复循环和遗漏要求。 - 点击监督意见查看对应证据，而不是接受无来源判断。 - 对监督意见进行采纳、忽略、标记误报或追问。 -- 对自动任务设置更严格的监督策略和人工检查点。 +- 对 Scheduled/Goal Task 设置更严格的监督策略和人工检查点。 ### 5.2 产品目标 @@ -97,8 +99,8 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写 | 对象 | 观察内容 | 典型用途 | | --- | --- | --- | | 普通会话 | 用户消息、助手回答、引用、工具事件 | 质量和证据评论 | -| 任务 | 目标、步骤、状态、工具、成果 | 偏离、循环和失败分析 | -| 自动化 Run | 触发、协议、预算、审批、指标 | 无人值守关注 | +| Task | 目标、状态、Conversation、成果 | 偏离、循环和失败分析 | +| Job/Run | 触发、步骤、协议、预算、审批、指标 | 无人值守或内部执行关注 | | 实验 Run | 协议、变量、指标、证据 | 协议一致性 | | 实验整体 | 各 Run 结算和比较 | 评估公平性与无结论提示 | @@ -156,7 +158,7 @@ type SupervisorAction = - 当前对象的名称、目标和约束。 - 最近有界消息。 - 工具名称、状态、参数摘要和输出摘要。 -- 任务和子任务状态。 +- Task、Job 和 Subjob 状态。 - 成果标题、类型、大小和有界摘要。 - 引用和知识检索诊断。 - 预算使用。 @@ -224,7 +226,7 @@ type SupervisorDecision = { - Ask 出现写工具请求。 - 工具或路径超出计划快照。 - 未经批准的跨项目或跨分区读取。 -- Token、时间、工具、子任务和成果预算。 +- Token、时间、工具、Job/Subjob 和成果预算。 - 幂等键冲突或结果未知。 - 输出 Schema 不匹配。 - 实验 Run 读取其他 Run 数据。 @@ -249,7 +251,11 @@ type SupervisorDecision = { ## 13. 用户交互 -### 13.1 右侧评论流 +### 13.1 工作栏监督栏目评论流 + +监督是助手工作栏中固定且始终可访问的栏目，不是只在聊天页面出现的附属面板。栏目默认 +跟随当前会话，用户也可以固定到其他普通 Conversation、Task、Job/Run 或 ExperimentRun。 +切换页面不会改变固定目标；目标失效时必须显示修复状态，不能静默回到当前会话。 复用魔法笔记的体验方向： @@ -272,7 +278,8 @@ type SupervisorDecision = { ### 13.2 会话输入区 -提供监督状态入口： +会话输入区可以提供当前会话监督的快捷入口，但不是监督能力的唯一入口，也不控制工作栏中 +已经固定到其他对象的监督目标： ```text 监督：关闭 / 综合 / 质疑 / 证据 / 目标 / 风险 @@ -311,7 +318,7 @@ open Supervisor 建议“暂停”时： 1. 创建 `request_review`。 -2. 在任务和会话界面显示原因和证据。 +2. 在任务自身的会话界面显示原因和证据。 3. 用户选择继续、暂停、调整目标或取消。 4. 用户操作进入任务审计。 diff --git a/docs/prd/task-and-job/README.md b/docs/prd/task-and-job/README.md new file mode 100644 index 0000000..fdd43db --- /dev/null +++ b/docs/prd/task-and-job/README.md @@ -0,0 +1,16 @@ +# Task 与 Job 文档集 + +本目录定义 GoodBuddy 的工作对象、内部执行单元和调度关系。 + +## 权威文档 + +1. [Task 与 Job 统一领域模型](./task-and-job-model.md)：术语、身份和对象关系。 +2. [Task Center PRD](./task-center-prd.md)：Task 的应用级索引。 +3. [Scheduled Task PRD](./scheduled-task-prd.md)：时间或事件触发的 Task。 +4. [Goal Task PRD](./goal-task-prd.md)：围绕可验证结果有界推进的 Task。 +5. [Job 与 Subjob PRD](./job-and-subjob-prd.md)：Task 内部串行、并行和委派执行。 + +## 阅读顺序 + +先阅读统一领域模型。其他三份文档不得重新定义 Task、Conversation、Job、Run 或 Subagent。 +若实现与文档出现冲突，应先修正统一模型，再同步功能 PRD。 diff --git a/docs/prd/task-and-job/goal-task-prd.md b/docs/prd/task-and-job/goal-task-prd.md new file mode 100644 index 0000000..e8b40f2 --- /dev/null +++ b/docs/prd/task-and-job/goal-task-prd.md @@ -0,0 +1,53 @@ +# Goal Task PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中，未来能力 | +| 版本 | 0.1 | +| 日期 | 2026-08-19 | +| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) | + +## 1. 产品定义 + +Goal Task 是围绕可验证结果持续推进的 Task。它仍然只有一个 Task Conversation；每轮观察、 +计划、行动和评估由 Job/Run 表达，不创建一串顶层 Task。 + +## 2. 必要配置 + +- 目标描述。 +- 至少一个成功标准。 +- 约束和停止条件。 +- 最大轮数、截止时间或预算。 +- 每轮评估方式。 +- 无进展处理。 +- Project、Runtime、知识、记忆、目录、工具和审批范围。 + +## 3. 有界循环 + +```text +Observe Job + → Planning Job + → Permission and budget check + → Action Job / parallel Jobs + → Evaluation Job + → Complete, pause, revise or continue +``` + +循环内的所有 Job 共享 Task Conversation。只有协调器把有意义的阶段进展写入消息时间线， +避免每个内部步骤产生一条顶层任务或杂乱消息。 + +## 4. 完成和无进展 + +- 模型声明不能单独证明目标完成。 +- 成功标准必须可计算或可人工审查。 +- 连续两轮没有指标改善、重复下一步、连续失败、权限不可用或预算不足时暂停。 +- 修改范围、预算、Runtime、工作模式或权限必须用户确认。 + +## 5. 验收原则 + +- [ ] Goal Task 只有一个 Task Conversation。 +- [ ] 循环步骤以 Job 表达，不创建顶层子 Task。 +- [ ] 没有成功标准和停止条件时不能启用。 +- [ ] 无进展和预算耗尽不会伪装为成功。 diff --git a/docs/prd/task-and-job/job-and-subjob-prd.md b/docs/prd/task-and-job/job-and-subjob-prd.md new file mode 100644 index 0000000..281346d --- /dev/null +++ b/docs/prd/task-and-job/job-and-subjob-prd.md @@ -0,0 +1,98 @@ +# Job 与 Subjob PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中，未来能力 | +| 版本 | 0.1 | +| 日期 | 2026-08-19 | +| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) | + +## 1. 目标 + +在不创建额外顶层 Task 或 Conversation 的前提下，让一个 Task 能够分解、串行、并行和委派 +多个执行单元，并将进展和结果有序汇入 Task 的同一 Conversation。 + +## 2. Job 类型 + +首期只使用有限类型： + +- `step`：Task 内一个明确步骤。 +- `scheduled_occurrence`：Scheduled Task 的一次到期执行。 +- `delegated`：交给 Subagent 或远程执行器。 +- `parallel_branch`：并行方案或分工。 +- `aggregation`：汇总多个前置 Job。 + +类型描述执行方式，不创造新的产品对象层级。 + +## 3. 并行模型 + +```text +Task Conversation + └─ Coordinating Job + ├─ Parallel Job A + ├─ Parallel Job B + ├─ Parallel Job C + └─ Aggregation Job +``` + +- 并行 Job 使用同一个 `taskId` 和 `conversationId`。 +- 每个 Job 有独立输入快照、状态、Run、预算和输出缓冲。 +- 并行 Job 不直接同时追加助手消息。 +- Aggregation Job 或 Task 协调器按确定顺序生成一条进展或结果消息。 +- 用户可以查看每个 Job 的详细活动，但主 Conversation 保持可读。 + +## 4. Subjob + +Job 可以创建有界 Subjob： + +- 默认最大深度 2。 +- 默认最大并发 3。 +- 默认最大子项数、模型调用、Token、耗时和输出大小由父 Job 预算限制。 +- 子级只能使用父级已授权能力的子集。 +- 父级取消、失败或超时后，活动子级必须取消。 + +## 5. Subagent + +Subagent 是 Job 的执行者： + +- 专家选择和路由记录在 Job 上。 +- Subagent 的原始流式输出进入有界 Job 缓冲和活动记录。 +- 完成、失败和部分输出都返回父 Job。 +- Subagent 不获得独立 Task Center 条目或 Conversation。 + +## 6. 状态与恢复 + +Job 状态至少包括： + +```text +queued → running → waiting_approval → completed + ↘ failed | cancelled | interrupted | budget_exceeded +``` + +- 重试创建新 Run，不覆盖失败 Run。 +- 应用退出将活动 Job 标记为 `interrupted`。 +- 有外部副作用且结果未知的 Job 不自动重试。 +- 聚合 Job 必须明确处理部分成功、全部失败和取消。 + +## 7. 界面 + +Task Conversation 显示： + +- 当前总体进展。 +- 并行 Job 数量和聚合状态。 +- 需要审批或用户输入的 Job。 +- 完成后的统一结果。 + +详细活动视图显示 Job 树、执行者、Runtime、耗时、预算、Run、错误和成果。Task Center 只显示 +Task 聚合状态，不展开 Job 树。 + +## 8. 验收标准 + +- [ ] 并行 Job 共享所属 Task 的 Conversation。 +- [ ] Job 不创建顶层 Task。 +- [ ] 并行输出不会无序污染消息时间线。 +- [ ] Subjob 深度、并发、预算和输出有界。 +- [ ] Subagent 失败能够返回部分输出和明确状态。 +- [ ] 父级取消传播到所有活动子级。 diff --git a/docs/prd/task-and-job/scheduled-task-prd.md b/docs/prd/task-and-job/scheduled-task-prd.md new file mode 100644 index 0000000..606be80 --- /dev/null +++ b/docs/prd/task-and-job/scheduled-task-prd.md @@ -0,0 +1,226 @@ +# Scheduled Task PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 当前基础能力已存在，扩展调度设计中 | +| 版本 | 0.4 | +| 日期 | 2026-08-19 | +| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) | +| 相关架构 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) | + +## 1. 产品定义 + +Scheduled Task 是带时间或事件触发器的 Task。它不是 Schedule 定义与临时 Task 的松散组合， +也不创建第二条 Conversation。 + +创建 Scheduled Task 时： + +1. 创建一个 Task。 +2. 为该 Task 创建唯一 Conversation。 +3. 保存 Schedule/Trigger Binding。 +4. 每次触发在同一 Task 内创建新的 Job 和 Run。 +5. 将面向用户的进展和结果持续写回同一 Task Conversation。 + +因此，一个每日任务在 Task Center 中始终是一条 Task，而不是每天新增一条 Task。 + +## 2. 当前能力 + +GoodBuddy 当前支持单次、每日和每周触发固定 Ask 提示，并持久化计划、Task、运行状态和成果。 +近期改进不得破坏现有数据、错过执行结算、暂停、立即运行和应用退出行为。 + +## 3. 目标 + +- 支持单次、每日、每周、每月、工作日和受限 Cron。 +- 支持 Task 完成、失败、Conversation 完成等内部事件触发。 +- 允许自然语言生成结构化草稿，但必须由用户检查后启用。 +- 提供时区、错过执行、幂等、租约、重试、恢复、取消、预算和审计。 +- 让所有重复触发复用同一 Task Conversation。 +- 为一次触发建立清晰 Job/Run，而不是创建新的顶层 Task。 + +## 4. 非目标 + +- 不提供任意脚本和循环的通用 DAG 编辑器。 +- 不允许模型生成并直接执行任意 Shell、SQL 或无限频率 Cron。 +- 不承诺应用退出后继续运行。 +- 不允许计划静默扩大权限、目录、知识或记忆范围。 +- 不把 Smart Heartbeat 变成 Scheduled Task。 +- 不把每次触发或重试显示为新的 Task。 + +## 5. 创建与配置 + +用户可以输入自然语言意图： + +```text +每周五下午 5 点总结本项目本周完成和失败的工作， +列出下周三个优先事项，不要修改文件。 +``` + +模型只生成草稿： + +- 名称和说明。 +- 时间或事件触发器。 +- 工作模式和 Runtime 建议。 +- Project、知识、记忆、目录和工具范围。 +- 输入、输出和通知。 +- 预算、并发和错过执行策略。 + +用户确认后，系统一次性创建 Task、Conversation 和 Schedule Binding。编辑计划只影响后续 +Job；已启动 Run 使用冻结快照。 + +## 6. 触发器 + +### 6.1 时间触发 + +```ts +type TimeTrigger = + | { type: 'once'; at: string; timezone: string } + | { type: 'daily'; localTime: string; timezone: string } + | { + type: 'weekly' + weekdays: number[] + localTime: string + timezone: string + } + | { + type: 'monthly' + day: number | 'last' + localTime: string + timezone: string + } + | { + type: 'cron' + expression: string + timezone: string + } +``` + +受限 Cron 使用五字段，不支持秒、年份、宏、`L`、`W`、`#` 或供应商扩展。Main 负责解析， +默认最小间隔为 15 分钟，并展示未来五次触发时间。 + +### 6.2 事件触发 + +后续支持： + +- `conversation.completed` +- `task.completed` +- `task.failed` +- `artifact.created` +- `knowledge.sync.completed` +- `magic_note.updated` + +事件触发配置来源范围、确定性过滤、去重窗口、冷却时间和并发上限。基础匹配不调用模型。 + +### 6.3 手动触发 + +“立即运行”在当前 Task 内创建独立 Job 和 Run，不改变下一次计划时间，不创建新 Task。 +重复点击使用调用级幂等键去重。 + +## 7. 一次触发的对象关系 + +```text +Scheduled Task + ├─ Conversation（持续复用） + ├─ Schedule Binding + └─ Job: scheduled_occurrence + └─ Run +``` + +- `scheduledFor` 和计划版本形成幂等键。 +- 同一 Scheduled Task 默认最多一个活动 occurrence Job。 +- 若允许并行 occurrence，它们仍属于同一 Task Conversation，并由协调器有序汇总。 +- 重试产生新 Run，不产生新 Task 或新 Job。 + +## 8. 错过执行 + +| 策略 | 行为 | +| --- | --- | +| `skip` | 记录跳过，不补跑 | +| `run_once` | 无论错过多少次，只在当前 Task 内补一个 Job | +| `catch_up_bounded` | 在数量和时间窗口上限内创建多个有界 Job | + +默认补跑最多 3 次、最多回溯 7 天。补跑同样受 Task 的并发、权限和预算控制。 + +## 9. 时区和夏令时 + +- 保存 IANA 时区，不保存固定 UTC 偏移。 +- 春季不存在的本地时间在当日第一个有效分钟触发。 +- 秋季重复时间只触发一次。 +- 系统时区变化不自动修改计划时区。 +- UI 显示计划时区、本机时区差异和未来触发时间。 + +## 10. Ask、Execute 与审批 + +第一阶段保持 Ask： + +- Runtime 边界只读。 +- 不写文件、不执行命令、不发送消息、不修改远程数据。 +- 输出写回 Task Conversation；独立交付物才进入成果。 + +Execute 按顺序开放： + +1. 有人值守，沿用逐工具审批。 +2. 预批准低风险工具和参数范围。 +3. 经过专项验证的内置无人值守模板。 + +高风险、越界或未预授权动作进入 `waiting_approval`，不能因定时触发而绕过策略。 + +## 11. 预算与背压 + +每个 Scheduled Task 配置： + +- 最大 Job 耗时。 +- 最大模型、Token 和工具调用。 +- 最大成果大小。 +- 最大活动 Job 数。 +- 后台优先级。 + +前台请求优先。后台达到上限时延后并记录 `deferred`，不能挤占用户正在等待的请求，也不能 +在恢复空闲时一次释放全部积压。 + +## 12. 重试、恢复和取消 + +- 瞬时、无副作用失败可以有界重试。 +- 配置、权限和范围错误不重试。 +- 外部副作用结果未知时进入 `outcome_unknown`，不自动重试。 +- 应用退出将活动 Job/Run 标记为 `interrupted`。 +- 暂停计划只阻止新 Job，不假装取消已发生的外部操作。 +- 取消 Task 必须传播到活动 Job、Subjob 和 Runtime。 + +## 13. 界面 + +Task Center 显示 Scheduled Task 的范围、状态、最近进展、需要关注和下次触发时间。点击条目 +打开同一 Task Conversation。 + +Task 内可查看： + +- 计划和触发器。 +- 下次执行和未来预览。 +- 每次 occurrence Job。 +- Run、审批、活动和成果。 + +不新增平行 Automation Center。 + +## 14. 兼容迁移 + +现有 Schedule、Schedule Run、Task 和 Conversation 数据渐进关联： + +- 保留现有计划 ID、启停状态、下次时间和历史。 +- 为每个现有计划建立或绑定一个持续 Task Conversation。 +- 历史每次执行映射为该 Task 下的 occurrence Job/Run。 +- 迁移不得复制消息、成果或顶层 Task。 + +## 15. 验收标准 + +- [ ] 创建 Scheduled Task 只创建一个 Task 和一个 Conversation。 +- [ ] 重复触发始终复用该 Task Conversation。 +- [ ] 每次触发创建 Job/Run，不创建新的顶层 Task。 +- [ ] 支持单次、每日、每周、每月、工作日和受限 Cron。 +- [ ] UI 显示计划时区和未来五次触发时间。 +- [ ] 夏令时不会造成漂移或双跑。 +- [ ] 错过执行按配置跳过、补一次或有界补跑。 +- [ ] 手动运行不改变下次计划时间。 +- [ ] Ask 在 Runtime 边界拒绝写操作和外部副作用。 +- [ ] 应用重启不自动重放结果未知的副作用。 +- [ ] Task Center 不因重复触发新增条目。 diff --git a/docs/prd/task-and-job/task-and-job-model.md b/docs/prd/task-and-job/task-and-job-model.md new file mode 100644 index 0000000..d2961c2 --- /dev/null +++ b/docs/prd/task-and-job/task-and-job-model.md @@ -0,0 +1,151 @@ +# Task 与 Job 统一领域模型 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 产品边界已确认，部分能力待实施 | +| 版本 | 0.1 | +| 日期 | 2026-08-19 | +| 适用产品 | GoodBuddy 桌面端 | +| 文档角色 | Task、Conversation、Job、Run 与 Subagent 的权威定义 | + +## 1. 核心定义 + +### 1.1 Task + +Task 是用户明确创建或由已启用计划创建的工作单位，也是 Task Center 的顶层对象。 + +- 创建 Task 就创建一条新的 Conversation。 +- Task 的内容载体是这条 Conversation，不再维护第二份任务正文或消息时间线。 +- 打开 Task 就打开其 Conversation。 +- Task 的目标、状态、范围、计划、Job、审批、活动和成果都围绕同一 Conversation 组织。 +- 一个 Task 在生命周期内保持同一个 `taskId` 和 `conversationId` 绑定。 + +普通 Conversation 不自动成为 Task。用户只是聊天时，不应因为存在模型调用或工具步骤就 +产生顶层 Task。 + +### 1.2 Conversation + +Conversation 是 Task 的交互和内容载体： + +- 保存用户消息、助手消息和面向用户的进展。 +- 承载同一 Task 内多个 Job 的可理解汇总。 +- 不让并行 Job 直接无序写入同一消息流；由 Task 协调器合并进展和结果。 +- 删除、归档和切换范围时遵循 Task 的生命周期规则。 + +### 1.3 Job + +Job 是 Task 内部的执行单位，不是新的顶层 Task： + +- 一次计划触发、一个执行步骤、一项专家委派或一组并行工作都可以是 Job。 +- 一个 Task 可以串行或并行运行多个 Job。 +- 所有 Job 仍属于同一个 Task 和同一条 Conversation。 +- Job 可以有自己的状态、预算、Runtime、执行者、输入快照和成果引用。 +- Job 不进入 Task Center；它显示在 Task 的时间线、活动或 Runtime 视图中。 + +### 1.4 Subjob + +Subjob 是 Job 的子执行单元。它用于分解和并发，不创建新的 Task 或 Conversation。 + +- 父 Job 负责合并 Subjob 结果。 +- 取消父 Job 必须传播到仍活动的 Subjob。 +- Subjob 不能扩大父 Job 的项目、目录、工具、知识、记忆或审批范围。 +- 深度、数量、并发、时间、Token 和输出大小必须有界。 + +### 1.5 Run + +Run 是 Task 或 Job 的一次执行尝试和审计记录，不是用户工作对象： + +- 重试、恢复或手动重新运行可以产生新的 Run。 +- Run 冻结当次配置、范围、预算和 Runtime。 +- Run 进入活动记录和审计，不进入 Task Center。 +- `completed` 只表示该次执行按协议结束，不必然表示 Task 目标达成。 + +### 1.6 Subagent + +Subagent 是执行 Job 或 Subjob 的受限执行者，不是对象层级： + +- 专家、Agent Runtime 或其他执行器可以承担 Job。 +- Subagent 不自动拥有独立 Task 或 Conversation。 +- Subagent 输出先回到所属 Job，再由 Task 协调器写入同一 Conversation。 + +## 2. 对象关系 + +```text +Task 1 ── 1 Conversation + │ + ├─ Schedule / Trigger Binding（可选） + ├─ Job 1 + │ ├─ Run 1..N + │ └─ Subjob 0..N + ├─ Job 2（可与 Job 1 并行） + └─ Artifact / Approval / Activity / Notification +``` + +不允许： + +```text +Task → 第二条 Conversation +Job → 新建顶层 Task +Subagent → 自动新建 Conversation +Run → 出现在 Task Center +``` + +## 3. Scheduled Task + +Scheduled Task 仍然是 Task，而不是独立的自动化对象： + +1. 用户创建 Scheduled Task。 +2. 系统创建一个 Task 和一个 Conversation，并保存 Schedule/Trigger Binding。 +3. 到期时在该 Task 内创建新的 Job 和 Run。 +4. 每次触发的进展和结果汇入同一个 Task Conversation。 +5. 编辑计划影响后续 Job，不修改已经启动的 Run。 + +同一 Scheduled Task 默认串行触发。需要并行时，应显式允许多个 Job 并发，并继续使用同一 +Conversation，而不是复制 Task。 + +## 4. 状态分层 + +| 层级 | 典型状态 | 用户在哪里看到 | +| --- | --- | --- | +| Task | queued、running、waiting_approval、paused、completed、failed、cancelled、interrupted | Task Center、Task Conversation | +| Job | queued、running、waiting、completed、failed、cancelled | Task 时间线、活动、Runtime | +| Run | claimed、running、completed、failed、cancelled、interrupted、budget_exceeded | 活动与审计 | + +Task 状态由当前目标和所属 Job 聚合得出，但不能用“任一 Job 完成”直接推断 Task 完成。 + +## 5. 兼容映射 + +当前代码和旧文档中的对象按以下方式收敛： + +| 旧概念 | 目标概念 | +| --- | --- | +| 自动任务 | Scheduled Task、Event Task 或 Goal Task | +| 自动会话 | 删除该独立概念，使用 Task Conversation | +| 子任务、Child Task | Job 或 Subjob | +| 专家子任务 | 由专家 Subagent 执行的 Job/Subjob | +| 多任务并行 | 一个 Task 内多个并行 Job；确实独立的用户目标才创建多个 Task | +| Schedule Run | Scheduled Task 内的 Job Run | +| Automation Run | Task 或 Job 的 Run | + +数据库字段可以在兼容期保留旧名称，但新产品文案、PRD 和新增契约必须使用本模型。 + +## 6. 安全和数据要求 + +- Main 验证 Task、Conversation、Job、Run 和 Project 的归属链。 +- Renderer 不能把任意 Job 绑定到其他 Task 或 Conversation。 +- Job/Subjob 继承父级能力上限，只能缩小，不能扩大。 +- 并行输出先有界持久化，再按确定顺序汇总到 Conversation。 +- 取消、超时、审批和应用退出必须沿 Task → Job → Subjob → Runtime 传播。 +- 用户删除 Task 时，先处理活动 Job，再按数据保留规则清理关联对象。 + +## 7. 验收原则 + +- [ ] 创建 Task 时只创建一条对应 Conversation。 +- [ ] Scheduled Task 的重复触发复用同一 Task Conversation。 +- [ ] 一个 Task 可以在同一 Conversation 下运行多个并行 Job。 +- [ ] Job、Subjob、Run 和 Subagent 不进入 Task Center。 +- [ ] 并行 Job 不直接无序写入 Conversation。 +- [ ] 取消和权限范围能够沿层级正确传播。 +- [ ] 新文档不再把 Job/Subjob 定义为新的顶层 Task。 diff --git a/docs/prd/task-and-job/task-center-prd.md b/docs/prd/task-and-job/task-center-prd.md new file mode 100644 index 0000000..26f12f2 --- /dev/null +++ b/docs/prd/task-and-job/task-center-prd.md @@ -0,0 +1,59 @@ +# Task Center PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-08-19 | +| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) | +| 界面归属 | [通用助手工作栏与执行空间](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) | + +## 1. 产品定义 + +Task Center 是所有 Task 的应用级单例索引。它不是第二份任务数据，也不是 Automation +Center。点击条目直接打开 Task 自身的 Conversation。 + +## 2. 收录边界 + +收录： + +- 用户明确创建的 Task。 +- Scheduled Task、Event Task 和 Goal Task。 +- 未来由用户确认创建的其他顶层 Task。 + +不收录： + +- 普通 Conversation。 +- Job、Subjob、Run、工具步骤或 Subagent。 +- Smart Heartbeat 配置、报告和建议。 +- 仅用于审计的活动记录。 + +## 3. 列表信息 + +每条 Task 至少显示： + +- 名称和 Global / Project 范围。 +- Task 类型和触发来源。 +- 当前聚合状态。 +- 最近一次面向用户的进展。 +- 最近活动时间。 +- 等待审批、失败或需要关注数量。 +- 下次计划时间（如适用）。 + +## 4. 交互 + +- 点击条目打开 Task Conversation。 +- 支持按需要关注、进行中、已暂停、已结束筛选。 +- 支持暂停、恢复、取消和打开详情，但不在窄栏复制完整 Job 时间线。 +- 后台变化更新状态和徽标，不自动抢占当前页面。 +- Task 的计划、Job、Run、审批和成果在 Task 自身或对应活动视图管理。 + +## 5. 验收标准 + +- [ ] Task Center 只展示 Task。 +- [ ] 点击 Task 不会跳转到另一条内容相同的附属 Conversation。 +- [ ] Job/Subjob/Run 不会重复成为顶层条目。 +- [ ] Scheduled Task 显示下次时间，但每次触发不新增 Task 条目。 +- [ ] Smart Heartbeat 不进入 Task Center。 diff --git a/docs/features/knowledge-retrieval-evaluation.md b/docs/quality/knowledge-retrieval-evaluation.md similarity index 100% rename from docs/features/knowledge-retrieval-evaluation.md rename to docs/quality/knowledge-retrieval-evaluation.md diff --git a/docs/long-term-assistant-roadmap.md b/docs/roadmap/long-term-assistant-roadmap.md similarity index 61% rename from docs/long-term-assistant-roadmap.md rename to docs/roadmap/long-term-assistant-roadmap.md index ecac534..e915f54 100644 --- a/docs/long-term-assistant-roadmap.md +++ b/docs/roadmap/long-term-assistant-roadmap.md @@ -6,9 +6,10 @@ | --- | --- | | 文档类型 | 产品路线图 | | 状态 | 规划中 | -| 版本 | 0.1 | -| 日期 | 2026-08-12 | +| 版本 | 0.3 | +| 日期 | 2026-08-19 | | 适用产品 | GoodBuddy 桌面端 | +| 相关设计 | [通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)、[Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md)、[智能心跳 PRD](../prd/smart-heartbeat/smart-heartbeat-prd.md) | ## 1. 文档目标 @@ -23,7 +24,7 @@ GoodBuddy 应能够： 1. 持续组织项目、会话、任务、成果和记忆，而不是只保存聊天记录。 2. 在明确授权下理解文件、知识库、截图、应用窗口和浏览器上下文。 3. 以只读问答、计划审查和受控执行三种模式完成工作。 -4. 在右侧工作栏中持续展示任务、上下文、成果、文件更改和预览。 +4. 在应用级助手工作栏中持续提供任务中心、监督、Runtime、终端、进程、工作区、浏览器、成果和上下文。 5. 支持后台任务、定时任务、失败恢复和桌面通知。 6. 让所有记忆、权限、上下文和远程传输可见、可审查、可撤销。 @@ -35,11 +36,11 @@ GoodBuddy 应能够： ┌──────────────┬──────────────────────────────┬──────────────────────┐ │ 左侧导航 │ 主工作区 │ 右侧工作栏 │ │ │ │ │ -│ 项目 │ 对话 / 知识库 / 活动 │ 任务 │ -│ 会话 │ │ 上下文 │ -│ 自动化 │ │ 成果 │ -│ 记忆 │ │ 文件与更改 │ -│ 设置 │ │ 预览 │ +│ 项目 │ 对话 / 知识库 / 活动 │ 任务中心 / 监督 │ +│ 会话 │ │ Runtime / 终端 │ +│ 智能心跳 │ │ 进程 / 工作区 │ +│ 记忆 │ │ 浏览器 / 成果 │ +│ 设置 │ │ 上下文 │ └──────────────┴──────────────────────────────┴──────────────────────┘ ``` @@ -48,15 +49,32 @@ GoodBuddy 应能够： - 窄窗口：右侧栏作为全屏抽屉。 - 右侧栏在对话、知识库和活动视图之间保持状态。 - 知识图谱实体详情复用同一右栏容器，不再维护独立布局。 +- 九个标准能力固定可达；能力、连接和数据状态可以变化，但应用不按当前上下文自动隐藏入口。 +- Task Center 是 Task 的单例索引；其他可绑定目标的能力支持跟随当前上下文或固定到用户选择的目标。 ### 3.2 右侧工作栏 -#### 任务 +本节的范围、选择、执行空间与安全契约以 +[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md) 为准。 -- 展示正在运行、等待审批、失败和最近完成的任务。 -- 支持查看步骤、进度、耗时和执行来源。 -- 支持取消、重试、恢复和打开关联会话。 -- 待审批项目在所有视图中持续可见。 +#### 任务中心 + +- 保留 Task Center 作为工作栏中的稳定入口，不先建设平行的独立任务或自动化平台。 +- 每个 Task 与唯一 Conversation 一对一绑定；打开 Task 就打开该 Conversation。 +- Task Center 只索引 Task，显示范围、状态、最近进展和需要关注信息。 +- 普通 Conversation、Job、Run、工具步骤、Subagent 和智能心跳事项不作为顶层 Task。 + +#### 监督、Runtime 与进程 + +- 监督展示所选会话、任务、自动化或实验的带证据评论和介入请求。 +- Runtime 展示所选会话或 Run 的工具、Subagent、后台 Job、Workflow/Hook 和生命周期。 +- 进程只展示并控制 GoodBuddy 创建、托管或明确接管的进程。 +- 待审批和高风险状态在所有栏目中持续可见，但不无条件抢占当前栏目。 + +#### 终端 + +- 用户可主动创建本机或 SSH 终端，并明确看到执行空间、目录和连接状态。 +- 用户终端与 Agent 工具执行分离，Agent 不得未经明确授权向终端注入输入。 #### 上下文 @@ -70,19 +88,20 @@ GoodBuddy 应能够： - 展示任务生成的文档、表格、演示文稿、PDF、图片、代码和网页。 - 支持打开、导出、在文件管理器中显示和继续修改。 - 成果必须关联项目、任务、运行和会话。 +- HTML 使用禁用脚本和网络的隔离静态预览，并同时提供源码视图。 -#### 文件与更改 +#### 工作区 -- 展示当前项目工作区文件树。 +- 展示用户选择的项目、本机或 SSH 工作区文件树。 - 展示创建、修改和删除文件。 - 文本文件提供 Diff，支持接受、撤销和在外部应用打开。 - 高风险变更继续经过独立审批层。 -#### 预览 +#### 浏览器 -- 首期支持 Markdown、纯文本、JSON、图片和安全本地网页预览。 -- 后续支持 PDF、Office 文档和数据表格。 -- 网页预览使用隔离环境，不允许任意 Node.js 或 Electron API。 +- 创建或选择 GoodBuddy 隔离浏览器会话，不控制用户已安装的浏览器。 +- 展示当前 URL、有界画面、状态和错误，并由用户进入明确交互模式。 +- 没有会话时提供创建入口，不隐藏浏览器栏目。 ## 4. 核心功能 @@ -111,13 +130,14 @@ GoodBuddy 应能够： - 执行快照固定工作目录、模型、技能、MCP 和权限策略。 - 设置变化不影响正在运行的任务。 -### 4.3 后台任务 +### 4.3 后台 Task 与 Job -- 任务状态：排队、运行、等待审批、暂停、完成、失败、取消、中断。 -- 应用隐藏后任务继续运行，应用退出后不承诺继续执行。 -- 重启时将未完成任务标记为中断，并允许用户恢复。 -- 任务事件先持久化，再发送给 Renderer，避免窗口刷新后丢失。 -- 父任务取消时必须取消所有子任务。 +- Task 拥有唯一 Conversation；内部步骤、委派、并行分支和重复触发使用 Job/Subjob。 +- Task 状态：排队、运行、等待审批、暂停、完成、失败、取消、中断。 +- 应用隐藏后 Job 可以继续运行，应用退出后不承诺继续执行。 +- 重启时将未完成 Run 标记为中断，并允许用户恢复。 +- Task/Job 事件先持久化，再发送给 Renderer，避免窗口刷新后丢失。 +- 取消 Task 时必须向所有活动 Job、Subjob 和 Runtime 传播。 ### 4.4 长期记忆 @@ -135,14 +155,22 @@ GoodBuddy 应能够： 用户可以查看、搜索、编辑、确认、拒绝、删除和要求忘记。敏感个人信息不得自动确认为长期记忆。 -### 4.5 成果和预览 +### 4.5 智能心跳 + +- 当前智能心跳继续提供周期回顾、报告、记忆建议、行动建议和运行历史。 +- “智能心跳”菜单入口负责完整配置，并支持 Global 或指定一个、多个 Project。 +- 任务中心和设置中心不复制智能心跳 CRUD。 +- 智能心跳长期方向是“未来分区记忆”，但数据结构、唤起模型、生命周期、页面以及与任务和 + 长期记忆的关系尚未设计，不能提前实现。 + +### 4.6 成果和预览 - 成果存储在应用管理目录或用户指定位置。 - 每个成果记录类型、MIME、校验值、大小、来源和更新时间。 - Renderer 只能通过受控 IPC 读取预览，不接收任意系统路径访问能力。 - 大文件采用流式或分页读取，并设定大小上限。 -### 4.6 定时任务 +### 4.7 定时任务 - 支持单次、每日、每周、每月和受限 Cron 规则。 - 保存时区、有效期、错过执行策略和输出位置。 @@ -150,13 +178,13 @@ GoodBuddy 应能够： - 应用启动及系统恢复时重新计算待执行任务。 - 同一计划同一时间点不得重复执行。 -### 4.7 桌面通知 +### 4.8 桌面通知 - 任务完成、失败、等待审批和定时任务结果可触发通知。 - 点击通知打开对应项目、任务或会话。 - 通知内容默认不包含敏感上下文。 -### 4.8 桌面上下文 +### 4.9 桌面上下文 首期采用显式选择： @@ -167,7 +195,7 @@ GoodBuddy 应能够： 不实现持续录屏、静默窗口监控或全局输入记录。授权策略可以持久化，采集内容默认不持久化。 -### 4.9 语音 +### 4.10 语音 - 首期提供按住说话和语音转文字。 - 转写结果先进入可编辑输入框，不自动发送。 @@ -175,7 +203,7 @@ GoodBuddy 应能够： - 麦克风权限仅在可信主窗口、显式语音会话和用户操作后开启。 - 音频转写完成后默认删除。 -### 4.10 远程委派 +### 4.11 远程委派 - 远程入口可从受信任 Webhook、企业 IM 或移动端创建任务。 - 默认仅允许使用明确配置的项目和能力。 @@ -184,13 +212,13 @@ GoodBuddy 应能够： - 所有远程任务记录来源、摘要、幂等键、权限和结果。 - 远程委派默认关闭。 -### 4.11 专家与多 Agent +### 4.12 专家与多 Agent - 专家包含名称、职责、系统指令、模型策略和能力白名单。 -- 主任务可创建受限子任务，并由专家并行执行。 +- Task 可创建受限 Job/Subjob，并交给专家 Subagent 串行或并行执行。 - 必须限制最大层级、并发、耗时、Token、工具次数和成果大小。 -- 子任务不能绕过父任务权限。 -- 主 Agent 负责整合结果，子 Agent 不直接向同一消息流并发写入。 +- Job/Subjob 不能绕过所属 Task 的权限和范围。 +- 协调器负责整合结果，并行 Subagent 不直接向同一 Conversation 无序写入。 ## 5. 数据与持久化 @@ -245,12 +273,14 @@ GoodBuddy 应能够： - Projects 与会话归属。 - Ask、Execute 工作模式与旧版 Plan 数据兼容。 -- 全局右侧栏。 -- 任务、上下文、成果、文件更改和预览页签。 +- 应用级助手工作栏壳层。 +- 固定任务中心、监督、Runtime、终端、进程、工作区、浏览器、成果和上下文九个能力入口。 +- 任务中心保持单例索引，其他可绑定能力支持跟随当前上下文或固定目标。 -### 阶段 2：后台任务 +### 阶段 2：Task 与 Job -- 持久化任务、运行和事件。 +- 持久化 Task、Job、Run 和事件。 +- 在现有 Task Center 补齐范围、状态、最近进展、需要关注和直接打开 Task Conversation。 - 取消、重试、恢复和审批收件箱。 - 托盘状态和桌面通知。 @@ -258,6 +288,7 @@ GoodBuddy 应能够： - 成果存储和安全预览。 - 项目记忆、确认流程和检索。 +- 智能心跳配置支持 Global 或指定一个、多个 Project，并在自己的菜单入口完成配置和处理。 - 统一上下文组装器。 ### 阶段 4：自动化与桌面上下文 @@ -272,7 +303,7 @@ GoodBuddy 应能够： ### 阶段 6：专家与远程委派 -- 专家注册和受限子任务。 +- 专家注册和受限 Job/Subjob。 - 多 Agent 编排。 - 企业 IM/Webhook 远程入口。 @@ -281,8 +312,9 @@ GoodBuddy 应能够： ### 8.1 右侧栏 - 三种窗口宽度下布局可用。 -- 跨主视图切换保持页签和折叠状态。 -- 任务、上下文和成果更新不要求离开当前对话。 +- 九个标准能力在主要视图中固定可达，应用不按能力自动隐藏。 +- 跨主视图切换保持栏目、折叠、跟随和固定目标状态。 +- 任务中心、监督、Runtime、终端、进程、工作区、浏览器、成果和上下文更新不要求离开当前主任务。 - 键盘可操作，并具备正确 ARIA 标签。 ### 8.2 Projects @@ -291,8 +323,11 @@ GoodBuddy 应能够： - 项目切换不会泄漏其他项目的上下文、记忆或任务。 - 旧会话可迁移且不丢失。 -### 8.3 任务 +### 8.3 Task +- 每个 Task 与唯一 Conversation 一对一绑定，用户无需理解第二层内容载体。 +- Task Center 入口保留，普通 Conversation、Job、Run 和心跳事项不会混入顶层列表。 +- 每个 Task 显示范围、状态、最近进展和需要关注信息，并可直接打开其 Conversation。 - 事件持久化后再展示。 - 取消、失败、重试和应用重启均有确定状态。 - 审批在全局右侧栏可见。 @@ -302,6 +337,8 @@ GoodBuddy 应能够： - 未确认记忆不会进入模型上下文。 - 用户删除后不再检索到。 - 每条记忆显示来源与作用域。 +- 智能心跳配置明确属于 Global 或指定 Project，当前报告和建议继续沿用已有生命周期。 +- 未来分区记忆完成独立设计前，不新增相关数据、页面或任务转换。 ### 8.5 安全 diff --git a/docs/computer-control-implementation-status.md b/docs/status/computer-control-implementation-status.md similarity index 100% rename from docs/computer-control-implementation-status.md rename to docs/status/computer-control-implementation-status.md