diff --git a/docs/电脑控制开发进度.md b/docs/computer-control-implementation-status.md similarity index 97% rename from docs/电脑控制开发进度.md rename to docs/computer-control-implementation-status.md index c52ada8..df0279f 100644 --- a/docs/电脑控制开发进度.md +++ b/docs/computer-control-implementation-status.md @@ -1,6 +1,14 @@ # GoodBuddy 电脑控制开发进度 -最后更新:2026-08-05 +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 文档类型 | 实施进度 | +| 状态 | 持续更新 | +| 版本 | 0.1 | +| 日期 | 2026-08-07 | +| 适用能力 | 电脑控制与托管浏览器 | ## 范围 diff --git a/docs/功能方案设计.md b/docs/cross-platform-assistant-product-design.md similarity index 99% rename from docs/功能方案设计.md rename to docs/cross-platform-assistant-product-design.md index 494adaf..f984298 100644 --- a/docs/功能方案设计.md +++ b/docs/cross-platform-assistant-product-design.md @@ -4,13 +4,16 @@ | 项目 | 内容 | | --- | --- | -| 产品代号 | GoodBuddy | +| 文档类型 | 产品设计基线 | +| 状态 | 初始方案 | +| 版本 | 0.1 | +| 日期 | 2026-07-29 | +| 适用产品 | GoodBuddy | | 产品形态 | 常驻型跨平台 AI 桌面助手 | | 目标平台 | Windows、macOS、Linux(含统信 UOS、银河麒麟) | | 目标架构 | x86_64、ARM64(含鲲鹏、飞腾) | | 推荐技术栈 | Electron + React + TypeScript + Vite | | 可选扩展 | Rust Sidecar,用于本地索引、OCR、文档解析等性能敏感任务 | -| 文档状态 | 初始方案 | 本文定义产品范围、功能模块、关键交互、权限安全、跨平台策略、非功能指标、版本路线及验收要求。产品参考通用 AI 桌面助手形态,不依赖任何第三方产品的私有实现。 diff --git a/docs/features/automation-goals-and-scheduling-prd.md b/docs/features/automation-goals-and-scheduling-prd.md new file mode 100644 index 0000000..beb0cd6 --- /dev/null +++ b/docs/features/automation-goals-and-scheduling-prd.md @@ -0,0 +1,399 @@ +# 自动任务、目标与调度 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/features/automation-platform-architecture.md b/docs/features/automation-platform-architecture.md new file mode 100644 index 0000000..0389027 --- /dev/null +++ b/docs/features/automation-platform-architecture.md @@ -0,0 +1,528 @@ +# 自动化、监督与记忆平台总体设计 + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-08-13 | +| 适用产品 | GoodBuddy 桌面端 | +| 文档角色 | 自动任务、目标、并行实验、会话监督、分区记忆与持续学习的总纲 | + +## 1. 背景 + +GoodBuddy 当前已经具备若干长期助手能力,但它们仍是彼此分离的功能: + +1. 定时任务支持单次、每日和每周触发,创建 Ask 任务并保存任务和成果。 +2. 智能心跳支持全局或项目范围的每日、每周回顾,读取有界会话、任务和已确认记忆, + 生成摘要、记忆建议和后续任务。 +3. 专家子任务支持有限并发和只读综合,但没有实验变量、重复运行、统一指标和结果晋升。 +4. 记忆已有全局、项目、会话三种作用域,以及偏好、事实、摘要、流程四种类型, + 但检索、来源、时态、冲突和运行级隔离仍不完整。 +5. 魔法笔记已经提供“内容旁持续出现 AI 评论”的交互,可作为会话监督的体验参考, + 但它只分析笔记或待办,不观察会话和任务运行。 + +如果继续把更多能力加入“智能心跳”,心跳将同时承担调度、总结、执行、监督、学习和 +记忆管理,最终无法解释一次后台行为为什么发生、读取了什么、是否越权、产生了什么影响。 + +本设计将这些能力统一到一个平台模型中,同时保留不同产品的清晰边界。 + +## 2. 核心产品判断 + +### 2.1 不把心跳升级成万能后台 Agent + +智能心跳应继续承担周期性观察和回顾,不直接成为所有自动化的宿主。 + +- 定时任务解决“何时执行一个已知任务”。 +- 目标任务解决“围绕结果持续规划和推进”。 +- 并行实验解决“隔离多个候选并用相同标准比较”。 +- 会话监督解决“独立观察并在必要时评论、告警或暂停”。 +- 记忆系统解决“哪些经验可以在什么范围内被未来运行读取”。 +- 持续学习解决“候选经验如何经过评估后改变未来行为”。 + +这些能力可以共享调度、运行、证据、预算和审计基础,但不能共享一段不断膨胀的提示词。 + +### 2.2 增加会话监督,但不把它等同于第二个聊天 Agent + +建议新增会话监督功能,并借鉴魔法笔记的右侧 AI 评论流: + +- 默认只观察和评论,不替用户发言。 +- 只依据可见消息、工具事件、任务状态、成果和目标进行判断。 +- 不读取或展示模型隐藏推理。 +- 评论必须引用具体消息、步骤或证据。 +- 模型监督可以建议暂停,只有确定性安全规则或用户预先批准的门禁才能自动暂停。 +- 监督器不能自动批准工具、扩大目录、跨项目读取记忆或修改安全策略。 + +### 2.3 先做分区和来源,再做知识图谱 + +GoodBuddy 当前最需要的不是立即引入重型图数据库,而是保证: + +1. 运行只能读取明确允许的记忆分区。 +2. 并行实验的各个 Run 不共享可变记忆。 +3. 每条记忆知道来自哪次会话、任务、监督判断或实验结果。 +4. 新事实与旧事实冲突时保留时态和证据,不静默覆盖。 +5. 记忆进入模型上下文前经过范围、状态、敏感度和预算过滤。 + +SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现明确的关系追踪和跨实体查询 +需求后,才考虑时间知识图谱。 + +### 2.4 学习必须有评估门和回滚 + +“生成一条总结并保存”不等于持续学习。只有当候选经验通过回放或实验验证,并能安全改变 +未来行为时,才构成学习闭环。 + +初期自动学习只允许产生可审查候选,不允许自动修改: + +- 工具权限和审批策略。 +- Electron 安全边界。 +- 项目根目录和数据访问范围。 +- Runtime 沙箱。 +- 系统级提示词。 +- 远程消息发送或其他外部副作用策略。 + +## 3. 目标 + +### 3.1 用户目标 + +- 用统一入口创建定时、事件、目标和实验型自动任务。 +- 清楚知道自动任务的触发原因、当前目标、运行状态、预算和停止条件。 +- 在一个工作台中观察多个候选运行,并追溯结论到原始证据。 +- 为重要会话启用独立监督,及时发现偏题、遗漏、矛盾、证据不足和风险。 +- 知道每条记忆属于哪个范围、从哪里产生、何时有效以及被哪些运行使用。 +- 审查、批准、拒绝或回滚系统提出的记忆、模板和策略改进。 + +### 3.2 产品目标 + +- 复用现有 Project、Conversation、Task、Run、Artifact、Approval 和 Notification 能力。 +- 为所有后台工作提供统一的幂等、租约、恢复、取消、预算和审计语义。 +- 保持 Ask 只读,Execute 继续经过现有能力和审批控制。 +- 保持本地优先,应用退出后不虚假承诺后台持续执行。 +- 保证项目、会话、自动化和实验 Run 之间的记忆隔离。 +- 先建立可观测和可评估能力,再允许任何形式的自动行为改变。 + +## 4. 非目标 + +本组设计不包含: + +- 将 GoodBuddy 变为需要常驻服务器、Redis 或云端控制面的多租户平台。 +- 在应用退出后依靠未安装的系统服务继续运行任务。 +- 默认允许无人值守高风险 Execute。 +- 让模型自行扩大工具、目录、知识库、记忆或网络访问范围。 +- 允许多个实验 Run 并发修改同一个用户工作区。 +- 记录键盘、持续录屏或静默监控其他应用。 +- 把隐藏推理链作为监督、记忆或审计数据保存。 +- 初期直接建设通用可视化工作流 DAG 编辑器。 +- 将模型评分当作没有误差的客观真值。 + +## 5. 统一领域模型 + +### 5.1 核心实体 + +```text +AutomationPlan + ├─ TriggerPolicy + ├─ ObjectiveSet + ├─ ExecutionProtocol + ├─ BudgetPolicy + ├─ ApprovalPolicy + ├─ SupervisorPolicy + └─ MemoryBinding + │ + └─ AutomationRun + ├─ Task / Child Task + ├─ Observation + ├─ SupervisorDecision + ├─ Artifact + ├─ Metric + └─ MemoryCandidate +``` + +| 实体 | 职责 | +| --- | --- | +| `AutomationPlan` | 用户可编辑的长期定义,描述做什么、为何做、何时做和允许做什么 | +| `TriggerPolicy` | 手动、时间、事件或条件触发,以及错过执行策略 | +| `ObjectiveSet` | 成功标准、优化指标、约束和停止条件 | +| `ExecutionProtocol` | 本次运行冻结的提示、步骤模板、变量、Runtime、工具和数据范围 | +| `BudgetPolicy` | 最大耗时、模型调用、Token、工具次数、子任务数、成果大小和并发 | +| `ApprovalPolicy` | 哪些动作可自动执行、哪些等待批准、哪些禁止 | +| `SupervisorPolicy` | 观察维度、触发频率、干预级别和确定性门禁 | +| `MemoryBinding` | 运行可读取和可写入哪些记忆分区 | +| `AutomationRun` | 一次触发产生的不可变运行快照和聚合状态 | +| `Observation` | 对消息、步骤、工具、指标或系统状态的结构化观察 | +| `SupervisorDecision` | `continue`、`comment`、`warn`、`request_review`、`pause` 或 `stop` | +| `Metric` | 可复现的运行指标及其计算来源 | +| `MemoryCandidate` | 尚未进入未来上下文的候选经验 | + +### 5.2 自动化类型 + +`AutomationPlan.kind` 第一阶段使用有限枚举,而不是任意工作流: + +| 类型 | 说明 | +| --- | --- | +| `scheduled_task` | 到点运行一个固定任务 | +| `heartbeat_review` | 周期性观察会话、任务和记忆,输出回顾和建议 | +| `goal_loop` | 围绕目标重复执行“观察、计划、行动、评估” | +| `experiment` | 生成隔离候选 Run,按统一协议评估和比较 | + +会话监督不是独立执行任务。它是可附着到 Conversation、Task、AutomationRun 或 +Experiment 的 `SupervisorPolicy` 和监督会话。 + +### 5.3 运行快照 + +每次启动必须冻结: + +- Plan 版本。 +- 项目和工作目录。 +- Runtime 和模型配置引用。 +- 工作模式。 +- 提示和变量。 +- 工具、Skills、MCP 和知识库范围。 +- 可读、可写记忆分区。 +- 监督策略和评估器版本。 +- 预算和并发限制。 +- 审批策略。 + +运行开始后的设置变化只影响下一次 Run。用户可以查看当前 Run 与最新 Plan 的差异。 + +## 6. 统一状态模型 + +### 6.1 Plan 状态 + +```text +draft → active ↔ paused → archived +``` + +- `draft`:未通过配置校验,不能自动触发。 +- `active`:可以被触发。 +- `paused`:保留定义和历史,不产生新 Run。 +- `archived`:只读保留,不能恢复运行,复制后可继续使用。 + +### 6.2 Run 状态 + +```text +queued + → running + → waiting_approval + → paused + → evaluating + → completed + +任意活动状态 + → failed | cancelled | interrupted | budget_exceeded | superseded +``` + +规则: + +- `completed` 只表示协议成功结束,不自动表示目标达成。 +- `goalStatus` 独立为 `met`、`not_met`、`inconclusive` 或 `not_applicable`。 +- 应用退出时活动 Run 标记为 `interrupted`,不自动重放有副作用步骤。 +- `waiting_approval` 不占用 LLM 并发配额。 +- 预算耗尽必须使用 `budget_exceeded`,不能伪装为普通失败。 + +### 6.3 Supervisor 状态 + +```text +inactive → observing → attention_required → paused → resolved +``` + +监督状态不覆盖 Run 状态。Run 可以仍在运行但存在 `attention_required`,也可以因确定性门禁 +进入 `paused`。 + +## 7. 统一运行循环 + +### 7.1 调度与执行分离 + +```text +Trigger + → AutomationCoordinator 声明 Run + → RunQueue 按优先级和预算排队 + → AutomationExecutor 创建 Task + → Runtime 执行 + → Supervisor 观察 + → Evaluator 计算指标 + → 结果、证据和候选记忆入库 + → 用户审查或后续 Run +``` + +`AutomationCoordinator` 只负责触发、声明和恢复,不直接调用模型。执行仍通过任务和 Runtime +边界完成。 + +### 7.2 优先级 + +默认优先级从高到低: + +1. 用户正在等待的前台对话。 +2. 用户手动启动的 Run。 +3. 等待批准后恢复的 Run。 +4. 到期定时任务。 +5. 目标循环和实验 Run。 +6. 心跳回顾、记忆巩固和维护。 + +后台任务必须可被背压延后。延后记录为 `deferred`,不得丢失,也不得在系统恢复空闲时一次性 +释放全部积压。 + +### 7.3 幂等和租约 + +- 每次计划触发使用 `planId + scheduledFor + planVersion` 形成幂等键。 +- 手动触发使用调用方提供的单次幂等键。 +- Run 和长步骤使用租约,租约过期后才能恢复或重试。 +- 有外部副作用的步骤还需要工具级幂等键,无法确认结果时进入 + `outcome_unknown`,不得自动重试。 +- 同一个 Plan 可以限制最大活动 Run 数,默认 1。 + +## 8. 触发模型 + +### 8.1 支持顺序 + +| 阶段 | 触发类型 | +| --- | --- | +| 第一阶段 | 手动、单次、每日、每周、每月、受限 Cron | +| 第二阶段 | 应用启动、会话完成、任务完成或失败、文件同步完成、变量变化 | +| 后续 | 用户定义的组合条件和外部受信任事件 | + +事件触发必须来自 Main 进程内的持久事件,不允许 Renderer 临时事件直接启动高影响自动化。 + +### 8.2 错过执行策略 + +| 策略 | 行为 | +| --- | --- | +| `skip` | 记录跳过,不补跑 | +| `run_once` | 无论错过多少次,只补一次 | +| `catch_up_bounded` | 在数量和时间窗口上限内补跑 | + +默认: + +- 日常摘要使用 `run_once`。 +- 高频事件使用 `skip` 或事件去重。 +- 不允许无限补跑。 + +## 9. 目标、协议和实验的关系 + +```text +目标:想得到什么结果 +协议:用什么固定方法尝试 +运行:协议的一次执行 +实验:同一问题下多个隔离协议或变量组合的运行集合 +监督:运行过程中独立判断是否偏离目标、违反约束或需要人工介入 +记忆:运行可读的历史经验,以及运行结束后提出的候选经验 +``` + +关键规则: + +- 没有可计算或可审查成功标准的目标,不允许宣称“已完成目标”。 +- 实验的最佳结果只在成功 Run 中选择。 +- 全部 Run 失败时,实验状态为失败,不生成伪最佳结果。 +- 模型生成的实验协议必须先由用户审查,或在只读、低成本模板中明确启用自动接受。 +- 实验结果不能直接修改生产自动化,只能创建候选版本。 + +## 10. 监督边界 + +监督分为两层: + +### 10.1 确定性监督 + +由代码执行,适合: + +- 权限、目录和工具白名单。 +- Token、耗时、并发和输出大小预算。 +- JSON Schema、状态机和幂等约束。 +- 明确的停止条件和指标阈值。 +- 数据分区和跨范围访问。 + +确定性监督可以阻止、暂停或终止运行。 + +### 10.2 模型监督 + +适合: + +- 目标偏移。 +- 计划遗漏。 +- 结论与证据不一致。 +- 多个候选之间的定性差异。 +- 用户可能需要澄清的歧义。 +- 质量、表达和风险评论。 + +模型监督默认只评论或请求关注。它不能替代确定性安全边界,也不能自动批准高风险动作。 + +## 11. 记忆边界 + +### 11.1 计划读取链 + +运行只读取显式绑定的分区。推荐优先级: + +```text +当前 Run +→ 当前 Automation +→ 当前 Conversation(如有关联) +→ 当前 Project +→ Global +``` + +每一层都有独立结果数和字符预算。低层记忆不能通过同名内容自动覆盖高层记忆, +冲突必须被标记并交给上下文组装器处理。 + +### 11.2 写入规则 + +- Run 只能直接写入自己的运行分区和候选区。 +- 向 Automation、Project 或 Global 晋升需要评估或用户确认。 +- 实验 Run 不能直接互相读取运行记忆。 +- Supervisor 的判断保存为观察或候选,不自动变成事实。 +- 被拒绝的候选保留摘要指纹,避免重复建议,同时不进入模型上下文。 + +## 12. 信息架构 + +建议将现有“智能心跳”逐步扩展为“自动化中心”,但保留心跳作为一种计划: + +```text +自动化中心 +├─ 概览 +│ ├─ 正在运行 +│ ├─ 等待审批 +│ ├─ 需要关注 +│ └─ 最近结果 +├─ 计划 +│ ├─ 定时任务 +│ ├─ 智能心跳 +│ ├─ 目标任务 +│ └─ 实验 +├─ 运行 +│ ├─ 时间线 +│ ├─ 任务与步骤 +│ ├─ 监督记录 +│ ├─ 指标与证据 +│ └─ 成果 +├─ 建议 +│ ├─ 记忆候选 +│ ├─ 后续任务 +│ └─ 学习候选 +└─ 设置 + ├─ 全局预算 + ├─ 后台优先级 + ├─ 通知 + └─ 数据保留 +``` + +会话页面增加可折叠“监督”右栏,与任务、上下文和成果并列,或在已有右侧工作栏中新增页签。 + +## 13. 安全与隐私 + +1. Ask 在 Runtime 边界保持只读,而不只是提示词要求只读。 +2. Execute 继续通过现有审批、沙箱、工具和目录控制。 +3. 无人值守只允许用户显式批准的能力集合;遇到未预授权动作时进入等待审批。 +4. Supervisor、Evaluator 和 Heartbeat 都把消息、工具输出、记忆和成果视为不可信数据。 +5. 监督器不能读取隐藏推理,只能读取产品允许持久化和展示的事件。 +6. 所有跨分区读取由 Main 根据绑定关系决定,Renderer 不能提交任意分区 ID。 +7. 记忆和监督证据不得包含密钥、认证头、Cookie、完整私有文件或未经限制的工具输出。 +8. 自动化产生的通知默认隐藏私人内容。 +9. 应用退出时停止调度和新执行,持久化中断状态,释放 Runtime 和租约。 +10. 清除项目时按外键和显式事务清理其计划、运行、运行分区、监督记录和候选, + 不影响 Global 或其他项目。 + +## 14. 可观测性 + +每个 Run 至少展示: + +- 触发来源和计划版本。 +- 计划目标和当前 `goalStatus`。 +- Runtime、工作模式和工作目录。 +- 实际读取的知识库与记忆分区。 +- 实际调用的模型、Token、工具、耗时和成果大小。 +- 当前预算和剩余预算。 +- 任务、步骤和子任务状态。 +- Supervisor 评论、证据、严重度和处理结果。 +- 评估器版本、指标和证据。 +- 产生的候选记忆或学习产物。 +- 重试、延后、中断和恢复原因。 + +不得只显示一个模糊的“自动化成功率”而隐藏失败 Run、跳过 Run 或无结论 Run。 + +## 15. 建议的数据模型增量 + +以下为设计建议,字段在实现前仍需共享 Zod Schema 和 SQLite 迁移细化: + +```text +automation_plans +automation_plan_versions +automation_triggers +automation_runs +automation_run_events +automation_metrics +automation_observations +supervisor_sessions +supervisor_decisions +memory_namespaces +memory_candidates +learning_artifacts +evaluation_cases +evaluation_results +experiments +experiment_variants +experiment_runs +``` + +现有 `schedules`、`schedule_runs`、`heartbeat_configs`、`heartbeat_runs`、 +`heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。迁移顺序应先增加统一只读视图和 +关联字段,再逐步让新计划使用统一模型。 + +## 16. 分阶段实施 + +### 阶段 0:统一术语和可观测性 + +- 固定 Plan、Run、Goal、Protocol、Supervisor、Observation、Memory Candidate 等概念。 +- 为现有定时任务、心跳和专家子任务建立统一活动视图。 +- 补充触发来源、运行版本、预算和读写范围展示。 + +### 阶段 1:调度与运行基础 + +- 统一 Run 声明、幂等、租约、恢复和错过执行策略。 +- 增加月度和受限 Cron。 +- 增加后台优先级与并发预算。 +- 保持现有任务执行器不变。 + +### 阶段 2:会话监督与分区记忆 + +- 上线评论型会话监督。 +- 增加 Automation 和 Run 记忆分区。 +- 建立来源、证据、时态、冲突和晋升流程。 + +### 阶段 3:目标任务 + +- 增加目标、成功标准、约束、预算和停止条件。 +- 支持有界的观察、计划、行动、评估循环。 +- 默认 Ask 或需要逐步审批的 Execute。 + +### 阶段 4:并行实验 + +- 变量和运行隔离。 +- 候选、重复、指标、证据、失败结算和最佳结果选择。 +- 复用现有任务和受限子专家并发。 + +### 阶段 5:持续学习 + +- 先建立回放集和评估门。 +- 再增加候选、Shadow、晋升、监控、衰减和回滚。 +- 初期只晋升记忆和自动化模板,不自动改变安全策略。 + +## 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) +- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md) + +## 18. 总体验收标准 + +- [ ] 心跳、定时、目标和实验使用统一的 Plan 与 Run 术语。 +- [ ] 每个自动 Run 都能解释触发原因、目标、范围、预算、状态和结果。 +- [ ] Ask 自动化无法调用写工具或产生外部副作用。 +- [ ] Execute 自动化不能绕过现有审批、沙箱和能力控制。 +- [ ] 会话监督默认只评论,不能替用户发言或批准工具。 +- [ ] 并行 Run 的变量、会话、运行记忆、任务和成果相互隔离。 +- [ ] 失败 Run 不参与最佳结果选择,全部失败不报告成功。 +- [ ] 记忆跨分区读取必须显式授权并可审计。 +- [ ] 候选经验在评估门和回滚能力完成前不能自动改变未来行为。 +- [ ] 应用重启后状态可恢复,但不会自动重放结果未知的副作用步骤。 diff --git a/docs/features/continuous-learning-prd.md b/docs/features/continuous-learning-prd.md new file mode 100644 index 0000000..e3647c6 --- /dev/null +++ b/docs/features/continuous-learning-prd.md @@ -0,0 +1,408 @@ +# 持续学习与评估门 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中,远期能力 | +| 版本 | 0.1 | +| 日期 | 2026-08-13 | +| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md)、[并行实验 PRD](./parallel-experiments-prd.md)、[分区记忆 PRD](./partitioned-memory-prd.md) | + +## 1. 背景 + +智能心跳已经可以生成摘要、后续任务和记忆候选,但这还不是完整学习: + +- 候选是否改善未来行为没有评估。 +- 一条反思是否会被检索和使用并不确定。 +- 没有 Baseline、回放集、Shadow、晋升和回滚。 +- 没有持续监控候选生效后的收益与退化。 +- 如果允许系统直接修改 Prompt、Skill 或规则,可能发生静默劣化。 + +持续学习必须建立为可观察、可评估、可批准、可回滚的闭环,而不是“让模型自动改自己”。 + +## 2. 产品定义 + +```text +Observe + → Propose candidate + → Validate structure and safety + → Evaluate against baseline + → Shadow + → Promote with approval + → Monitor + → Keep, revise, rollback or archive +``` + +学习产物只有在改变未来行为后才算生效;只保存一条 Reflection 仍属于记忆候选。 + +## 3. 已确认的产品决策 + +1. 评估门必须先于任何自动应用能力上线。 +2. 新候选默认 `candidate`,通过离线评估后先进入 `shadow`。 +3. 第一阶段只允许人工晋升。 +4. 每次晋升必须记录 Baseline、候选、评估结果、作用域和回滚版本。 +5. 学习不能修改安全边界、工具审批、目录权限、沙箱或 Electron 配置。 +6. 失败案例和用户负反馈只作为评估数据,不直接成为新规则。 +7. 回放案例必须脱敏、版本化,并得到用户明确选择或来自仓库公开样例。 +8. 模型评估不是唯一真值,优先使用确定性验收和人工反馈。 +9. 生效后的候选继续监控,发生退化可自动停用,但不能自动换上另一个候选。 +10. 没有足够证据时保持 `inconclusive`,不强行晋升。 + +## 4. 学习产物 + +首期只支持: + +| 产物 | 作用 | 是否可自动应用 | +| --- | --- | --- | +| Memory | 改善相关上下文召回 | 否,人工确认 | +| Automation Template | 改善目标、步骤、提示或预算默认值 | 否,创建新草稿 | +| Prompt Variant | 用于实验比较 | 否 | +| Rubric | 改善评估标准 | 否 | +| Retrieval Preference | 调整特定 Automation 的检索配置候选 | 否 | + +后续评估: + +| 产物 | 风险 | +| --- | --- | +| Skill | 可能扩大行为和工具使用 | +| Procedure | 可能长期影响多个任务 | +| Non-security Rule | 可能阻断或改变行为 | +| Agent Preference | 可能产生难以解释的个性漂移 | + +永久禁止自动学习修改: + +- 工具权限和审批策略。 +- 工作区根目录和文件访问范围。 +- 网络、远程消息和电脑控制权限。 +- Electron 安全设置。 +- API Key、凭据和 Provider Endpoint。 +- 删除、支付、发布和生产操作政策。 + +## 5. 候选来源 + +- 用户对回答、任务或 Supervisor 意见的显式反馈。 +- 智能心跳提出的重复模式。 +- 自动化 Run 的成功与失败比较。 +- 并行实验结论。 +- 回放评估发现的稳定差异。 +- 用户手动创建。 + +候选必须包含: + +- 作用域。 +- 产物类型。 +- 来源证据。 +- 预期改善的指标。 +- 可能影响的行为。 +- 风险级别。 +- Baseline 引用。 +- 建议的评估集。 + +模型不能仅凭一条成功案例宣称“已学习”。 + +## 6. 状态机 + +```text +candidate + → evaluating + → rejected + → inconclusive + → shadow + → awaiting_approval + → promoted + → paused + → rolled_back + → archived +``` + +| 状态 | 含义 | +| --- | --- | +| `candidate` | 尚未评估 | +| `evaluating` | 正在运行离线评估 | +| `rejected` | 明确退化、安全不合格或无效 | +| `inconclusive` | 证据不足 | +| `shadow` | 计算候选决策但不影响真实行为 | +| `awaiting_approval` | 达到晋升标准,等待用户 | +| `promoted` | 已作为指定作用域的当前版本 | +| `paused` | 暂停影响,保留版本 | +| `rolled_back` | 已恢复前一版本 | +| `archived` | 不再评估和使用 | + +## 7. 评估案例 + +### 7.1 案例来源 + +优先级: + +1. 仓库内公开、无隐私的固定评测样例。 +2. 用户手动创建的案例和期望。 +3. 用户明确选择并脱敏的历史会话或任务。 +4. 实验中产生、经用户批准保留的案例。 + +禁止默认采样所有私人会话用于学习。 + +### 7.2 案例结构 + +```ts +type EvaluationCase = { + id: string + suiteId: string + input: EvaluationInput + assertions: EvaluationAssertion[] + forbiddenBehaviors: EvaluationAssertion[] + source: EvaluationCaseSource + sensitivity: 'public' | 'private_local' + version: number +} +``` + +断言可以是: + +- 输出符合 Schema。 +- 包含或不包含确定文本模式。 +- 引用来自允许知识库。 +- 不调用工具。 +- 任务状态和成果存在。 +- 测试命令通过。 +- 人工评分。 +- 模型 Rubric 分项。 + +### 7.3 冻结 + +一次评估冻结: + +- 案例版本。 +- Baseline 版本。 +- Candidate 版本。 +- Runtime 和模型。 +- 知识、记忆和工作区快照。 +- 预算。 +- 评估器版本。 + +设置变化不改变已开始的评估。 + +## 8. 评估门 + +### 8.1 判定 + +```ts +type GateVerdict = { + decision: 'reject' | 'inconclusive' | 'shadow' + baselineMetrics: MetricValue[] + candidateMetrics: MetricValue[] + regressions: Regression[] + caseIds: string[] + evaluatorVersions: string[] + notes: string +} +``` + +最小规则: + +1. 任何安全、权限或硬约束退化立即 Reject。 +2. 确定性质量指标不能低于配置阈值。 +3. 成本和延迟退化必须在允许范围。 +4. 开放质量指标至少非退化,或收益足以覆盖明确成本。 +5. 案例数或评估器不足时 Inconclusive。 +6. 通过离线门只进入 Shadow,不直接 Promote。 + +### 8.2 Baseline + +Baseline 是当前已生效版本或明确的无候选行为。不能用另一个同时变化的实验配置充当 Baseline。 + +### 8.3 多模型评估 + +模型 Rubric 可使用与被评候选不同的模型,但必须: + +- 固定版本和提示。 +- 隐藏候选身份。 +- 随机化顺序。 +- 保存分项和证据。 +- 在关键晋升中结合确定性或人工评估。 + +## 9. Shadow + +Shadow 模式: + +- 接收与当前真实行为相同的有界输入。 +- 计算候选会做出的选择或输出。 +- 不调用有副作用工具。 +- 不替换用户看到的结果。 +- 不写入长期记忆。 +- 保存与实际结果可比较的指标。 + +对于成本较高的候选: + +- 只对抽样的已授权案例运行。 +- 用户可设置月度调用上限。 +- 系统繁忙时延后。 + +Shadow 达到配置的最小观察数且无安全退化后进入 `awaiting_approval`。 + +## 10. 晋升 + +晋升对话框必须显示: + +- 候选将改变什么。 +- 作用域和受影响计划。 +- 来源。 +- Baseline 与 Candidate 指标。 +- 失败案例和不确定性。 +- 额外成本。 +- 回滚版本。 + +用户可以: + +- 晋升。 +- 继续 Shadow。 +- 拒绝。 +- 缩小作用域后重新评估。 + +晋升采用原子版本切换。不能在一半对象上成功、一半失败。 + +## 11. 上线后监控 + +监控: + +- 使用次数。 +- 成功、失败和无结论。 +- 确定性指标。 +- 用户采纳、撤销和负反馈。 +- Token、耗时和工具调用变化。 +- Supervisor 警告变化。 + +自动暂停条件: + +- 安全或权限硬约束失败。 +- 确定性错误率超过阈值。 +- 连续崩溃或格式失败。 +- 成本超过批准上限。 + +自动暂停只恢复到上一已批准版本,并通知用户。系统不能自行选择新候选替代。 + +## 12. 回滚 + +- 每个 Promoted 产物有不可变版本。 +- 保存前一版本和作用域绑定。 +- 一键回滚使用原子切换。 +- 回滚不删除失败版本,保留指标和原因。 +- 当前有运行使用该版本时,只影响下一次 Run;紧急安全暂停可取消尚未开始的 Run。 +- 被回滚候选再次晋升必须重新评估。 + +## 13. 衰减与归档 + +- 长期未使用的候选和 Shadow 可归档。 +- Promoted 产物不因时间静默删除。 +- Memory 类型遵守分区记忆的衰减规则。 +- 评估案例变化后,相关候选标记为“评估过期”。 +- 模型或 Runtime 大版本变化时,可要求重新回放。 +- 归档保留不含私人正文的指标和版本元数据。 + +## 14. 信息架构 + +建议在自动化中心增加“学习”: + +1. **候选**:来源、作用域、预期收益和风险。 +2. **评估中**:进度、案例和预算。 +3. **Shadow**:观察数、差异和成本。 +4. **待批准**:晋升摘要。 +5. **已生效**:当前版本、使用量和健康状态。 +6. **历史**:拒绝、回滚和归档。 + +候选详情页签: + +- 概览。 +- 变更 Diff。 +- 评估案例。 +- 指标和失败。 +- Shadow。 +- 版本与回滚。 + +## 15. 数据模型建议 + +```ts +type LearningArtifact = { + id: string + scopeKind: 'global' | 'project' | 'automation' | 'agent' + scopeId?: string + kind: + | 'memory' + | 'automation_template' + | 'prompt_variant' + | 'rubric' + | 'retrieval_preference' + status: + | 'candidate' + | 'evaluating' + | 'rejected' + | 'inconclusive' + | 'shadow' + | 'awaiting_approval' + | 'promoted' + | 'paused' + | 'rolled_back' + | 'archived' + payload: JsonValue + sourceRefs: LearningSourceRef[] + baselineVersionId?: string + promotedVersionId?: string + createdAt: string + updatedAt: string +} +``` + +建议表: + +- `learning_artifacts` +- `learning_artifact_versions` +- `evaluation_suites` +- `evaluation_cases` +- `evaluation_runs` +- `evaluation_results` +- `shadow_observations` +- `promotion_events` +- `rollback_events` + +## 16. 安全与隐私 + +1. Apply 层拒绝没有 Gate Verdict 的候选。 +2. 产物类型和目标作用域使用代码白名单。 +3. 安全与权限配置不在可学习目标白名单中。 +4. 私人评估案例只在本地使用,不导出或发送到未授权 Provider。 +5. Shadow 不调用有副作用工具。 +6. Candidate 内容和评估输出都视为不可信数据。 +7. Renderer 不能直接设置 Promoted 状态,Main 验证评估与审批。 +8. 删除私人评估案例后清理派生缓存和 Embedding。 +9. 日志不记录完整案例、Prompt、回答、文件或凭据。 +10. 自动暂停采用确定性条件,不依赖模型自由判断。 + +## 17. 实施顺序 + +严格顺序: + +1. 建立版本化评估案例和确定性断言。 +2. 复用并行实验运行 Baseline 与 Candidate。 +3. 实现 Gate Verdict,只有 Reject、Inconclusive 和 Shadow。 +4. 实现 Shadow,但不允许 Apply。 +5. 实现人工晋升和原子回滚。 +6. 实现上线监控和确定性自动暂停。 +7. 首先开放 Memory 和 Automation Template。 +8. 经过长期验证后再评估 Skill、Procedure 和非安全规则。 + +不能先做自动改 Prompt,再补评估门。 + +## 18. 验收标准 + +- [ ] 没有评估结果的候选无法晋升。 +- [ ] 安全、权限或硬约束退化必定 Reject。 +- [ ] 评估不足时显示 Inconclusive,不强行选优。 +- [ ] Baseline、Candidate、案例、Runtime 和评估器都被冻结和版本化。 +- [ ] Shadow 不影响用户结果、不调用副作用工具、不写长期记忆。 +- [ ] 晋升前展示收益、退化、成本、作用域和回滚版本。 +- [ ] 第一阶段只有用户可以批准晋升。 +- [ ] 晋升和回滚采用原子版本切换。 +- [ ] 生效后出现确定性严重退化时自动暂停并恢复上一批准版本。 +- [ ] 系统不会自动选择另一个候选替代。 +- [ ] 私人会话不会默认进入评估集。 +- [ ] 安全策略、权限、目录、凭据和 Electron 配置不属于可学习产物。 diff --git a/docs/features/conversation-supervision-prd.md b/docs/features/conversation-supervision-prd.md new file mode 100644 index 0000000..f5e3478 --- /dev/null +++ b/docs/features/conversation-supervision-prd.md @@ -0,0 +1,409 @@ +# 会话监督 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-08-13 | +| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md) | +| 体验参考 | GoodBuddy 魔法笔记 AI 评论流 | + +## 1. 背景 + +GoodBuddy 的魔法笔记已经提供一种有价值的交互:用户持续写作,AI 在右侧以长评、建议和 +警告进行评论,用户可以选择综合、扩展、润色、质疑或发散方向。该能力是内容分析,不是 +会话监督: + +- 只分析当前笔记或待办文本。 +- 不观察聊天任务、工具调用、目标、预算或成果。 +- 不参与任务状态机。 +- 不引用具体会话步骤。 +- 不支持关注、暂停和解决流程。 + +随着目标任务和并行实验出现,用户需要一个与执行 Agent 相互独立的观察者,帮助发现偏题、 +遗漏、矛盾、证据不足、循环、成本失控和潜在风险。 + +## 2. 产品定义 + +会话监督是在明确范围和策略下,对 Conversation、Task、AutomationRun 或 ExperimentRun +的可见事件进行独立观察,产生带证据的评论、告警和人工介入请求。 + +它不是: + +- 第二个替用户发言的聊天 Agent。 +- 隐藏推理查看器。 +- 工具审批器。 +- 可以绕过安全边界的“总管理员”。 +- 自动修正执行过程的通用控制器。 + +## 3. 核心产品判断 + +建议增加会话监督,首期采用“魔法笔记式右侧评论流”,但只开放以下能力: + +```text +观察 +→ 评论 / 警告 +→ 用户查看证据 +→ 用户忽略、采纳、询问、暂停或调整任务 +``` + +首期模型监督不自动暂停。只有现有确定性安全规则、预算和用户显式配置的硬门禁可以自动暂停。 + +## 4. 已确认的产品决策 + +1. 监督默认关闭,由用户对会话、任务、自动化或实验显式启用。 +2. 监督只读取用户可查看的消息、工具事件、状态、指标、成果摘要和目标。 +3. 不读取、推断或保存模型隐藏推理链。 +4. 每条重要判断必须引用具体消息、工具、步骤、指标或成果。 +5. 模型监督默认只评论、警告或请求人工复核。 +6. 确定性监督负责权限、预算、Schema、幂等和硬停止条件。 +7. 监督器不能自动批准工具、扩大范围、修改安全策略或替用户发送消息。 +8. 监督评论不是长期事实,默认不进入记忆。 +9. 监督调用使用独立预算和低于前台对话的优先级。 +10. 同一个事件不能同时产生重复页内警告、评论和全局通知。 + +## 5. 目标 + +### 5.1 用户目标 + +- 在重要会话旁获得不中断主对话的独立评论。 +- 及时发现目标偏移、缺少证据、相互矛盾、重复循环和遗漏要求。 +- 点击监督意见查看对应证据,而不是接受无来源判断。 +- 对监督意见进行采纳、忽略、标记误报或追问。 +- 对自动任务设置更严格的监督策略和人工检查点。 + +### 5.2 产品目标 + +- 为普通会话、目标任务和实验提供统一监督契约。 +- 让确定性安全门禁与模型质量判断保持分层。 +- 保存有界、可审计的监督事件,而非复制完整会话。 +- 将用户反馈用于调整规则和评估监督器,但不自动训练或改策略。 + +## 6. 非目标 + +- 不展示内部 Chain of Thought。 +- 不持续监控其他应用、键盘、麦克风或屏幕。 +- 不把 Supervisor 设为拥有所有工具的超级 Agent。 +- 不自动修改用户消息或助手回答。 +- 不保证识别所有事实错误、偏见或安全风险。 +- 不把一次模型警告作为任务失败的确定性依据。 +- 不在首期支持 Supervisor 与执行 Agent 自主多轮辩论。 +- 不让 Supervisor 读取未授权项目、会话、知识库或记忆。 + +## 7. 监督对象 + +| 对象 | 观察内容 | 典型用途 | +| --- | --- | --- | +| 普通会话 | 用户消息、助手回答、引用、工具事件 | 质量和证据评论 | +| 任务 | 目标、步骤、状态、工具、成果 | 偏离、循环和失败分析 | +| 自动化 Run | 触发、协议、预算、审批、指标 | 无人值守关注 | +| 实验 Run | 协议、变量、指标、证据 | 协议一致性 | +| 实验整体 | 各 Run 结算和比较 | 评估公平性与无结论提示 | + +每个监督会话只能绑定一个主对象,并继承其项目范围。 + +## 8. 监督模式 + +### 8.1 评论方向 + +借鉴魔法笔记,普通会话支持: + +| 模式 | 行为 | +| --- | --- | +| 综合 | 平衡总结目标、进展、风险和下一步 | +| 质疑 | 检查逻辑跳跃、前提、反例和证据 | +| 证据 | 检查重要结论是否有可追溯依据 | +| 目标 | 检查是否回应用户目标和约束 | +| 风险 | 检查权限、隐私、外部影响和不可逆行为 | + +自动化和实验可组合多个检查维度,不用方向单选替代确定性规则。 + +### 8.2 触发方式 + +| 方式 | 说明 | +| --- | --- | +| 手动 | 用户点击“检查当前会话” | +| 每次回复后 | 助手一轮完成后异步分析 | +| 每 N 步 | 自动化或实验按有界步骤间隔分析 | +| 关键事件 | 工具失败、预算 80%、等待审批、指标异常 | +| Run 结束 | 进行最终监督回顾 | + +首期优先手动和每次回复后。草稿输入不发送给监督器,除非未来明确增加类似魔法笔记的 +草稿评论模式。 + +### 8.3 干预级别 + +```ts +type SupervisorAction = + | 'continue' + | 'comment' + | 'warn' + | 'request_review' + | 'pause' + | 'stop' +``` + +- 模型 Supervisor 首期只可产生前四种。 +- `pause` 和 `stop` 只来自确定性门禁或用户操作。 +- 后续若允许模型建议暂停,仍需确定性策略把建议转换为 `request_review` 或经过用户预授权。 + +## 9. 观察输入 + +### 9.1 可见输入 + +- 当前对象的名称、目标和约束。 +- 最近有界消息。 +- 工具名称、状态、参数摘要和输出摘要。 +- 任务和子任务状态。 +- 成果标题、类型、大小和有界摘要。 +- 引用和知识检索诊断。 +- 预算使用。 +- 明确配置的监督规则。 +- 已解决或被忽略的近期监督意见摘要。 + +### 9.2 禁止输入 + +- API Key、Token、Cookie 和认证头。 +- 模型隐藏推理。 +- 未授权文件和完整私人文档。 +- 其他项目、会话或实验 Run 的数据。 +- 原始无限长度工具输出。 +- 已删除或用户要求忘记的记忆。 + +### 9.3 上下文窗口 + +- 普通会话默认最近 12 条消息和最多 24,000 字符。 +- 任务按最近 20 个关键事件和当前目标组装。 +- 长会话先使用确定性提取,再由监督器处理有界输入。 +- 不能把 Supervisor 自己的旧评论无限回填,最多保留近期未解决摘要。 + +## 10. 监督输出 + +```ts +type SupervisorDecision = { + action: + | 'continue' + | 'comment' + | 'warn' + | 'request_review' + category: + | 'goal_drift' + | 'missing_requirement' + | 'evidence_gap' + | 'contradiction' + | 'repetition' + | 'quality' + | 'risk' + | 'budget' + severity: 'info' | 'low' | 'medium' | 'high' + title: string + content: string + evidence: SupervisorEvidenceRef[] + confidence: number + suggestedActions: SupervisorSuggestedAction[] +} +``` + +证据引用可以指向: + +- `messageId` +- `toolCallId` +- `taskEventId` +- `artifactId` +- `metricId` +- `approvalId` + +没有有效证据时,严重度最多为 `low`,且必须显示“推测”。 + +## 11. 确定性监督 + +以下检查由代码执行: + +- Ask 出现写工具请求。 +- 工具或路径超出计划快照。 +- 未经批准的跨项目或跨分区读取。 +- Token、时间、工具、子任务和成果预算。 +- 幂等键冲突或结果未知。 +- 输出 Schema 不匹配。 +- 实验 Run 读取其他 Run 数据。 +- 硬停止条件和必填成果。 + +确定性监督可以阻止、暂停或终止运行。结果必须包含规则 ID、实际值、阈值和触发事件, +不通过模型重新解释才能生效。 + +## 12. 模型监督 + +适合判断: + +- 回答是否偏离用户问题。 +- 计划是否遗漏明确要求。 +- 重要结论是否缺少证据。 +- 当前回答与前文是否矛盾。 +- 是否重复尝试而没有进展。 +- 是否存在值得用户注意的模糊风险。 + +模型监督输出严格经过 Schema 校验。格式错误最多修复一次;失败不阻塞普通前台会话, +但在配置为自动化门禁时必须明确记录“监督不可用”,不能假装检查通过。 + +## 13. 用户交互 + +### 13.1 右侧评论流 + +复用魔法笔记的体验方向: + +- 长评卡。 +- 建议卡。 +- 警告卡。 +- 证据链接。 +- 评论方向和时间。 + +每条意见操作: + +- 查看证据。 +- 采纳建议。 +- 追问。 +- 忽略。 +- 标记误报。 +- 对自动化请求暂停。 + +“采纳”只是把建议带入输入框、计划草稿或任务操作,不让 Supervisor 直接执行。 + +### 13.2 会话输入区 + +提供监督状态入口: + +```text +监督:关闭 / 综合 / 质疑 / 证据 / 目标 / 风险 +``` + +这是持久二元启用加方向选择: + +- 是否启用使用共享 Switch,`role="switch"`。 +- 方向使用 `SegmentedControl` 或上下文单选菜单。 +- 不把开关和方向做成一组含义不清的页签。 + +### 13.3 关注状态 + +会话或任务列表显示未解决意见数量和最高严重度,不能只用颜色。 +只有 `request_review`、高风险警告或确定性暂停触发全局通知。 + +## 14. 解决流程 + +```text +open + → acknowledged + → resolved + → dismissed + → false_positive +``` + +- `acknowledged`:用户已查看,尚未解决。 +- `resolved`:用户或后续运行说明已处理。 +- `dismissed`:不采纳,但不一定是误报。 +- `false_positive`:明确标记判断不正确。 + +后续监督输入可以包含未解决意见摘要,已解决意见默认不重复提醒。 + +## 15. 与任务控制的关系 + +Supervisor 建议“暂停”时: + +1. 创建 `request_review`。 +2. 在任务和会话界面显示原因和证据。 +3. 用户选择继续、暂停、调整目标或取消。 +4. 用户操作进入任务审计。 + +确定性门禁暂停时: + +1. Run 进入 `paused` 或 `waiting_approval`。 +2. 显示规则、阈值和实际值。 +3. 只有满足规则或用户完成对应审批后才能恢复。 +4. 模型评论不能覆盖门禁。 + +## 16. 与记忆的关系 + +- 监督评论默认保存在监督记录,不属于长期记忆。 +- 用户采纳后可以手动创建记忆候选。 +- “事实错误”“用户偏好”等监督判断不能自动写入 Project 或 Global。 +- 多次被用户标记误报的模式进入监督评估数据,不直接改变 Prompt。 +- 监督器可以读取绑定范围内的已确认记忆,但必须在证据中标明记忆来源。 + +## 17. 数据模型建议 + +```ts +type SupervisorSession = { + id: string + projectId?: string + targetType: 'conversation' | 'task' | 'automation_run' | 'experiment' + targetId: string + enabled: boolean + mode: 'general' | 'challenge' | 'evidence' | 'goal' | 'risk' + triggerPolicy: SupervisorTriggerPolicy + budget: SupervisorBudget +} + +type SupervisorRecord = { + id: string + sessionId: string + source: 'deterministic' | 'model' + decision: SupervisorDecision + status: + | 'open' + | 'acknowledged' + | 'resolved' + | 'dismissed' + | 'false_positive' + createdAt: string + resolvedAt?: string +} +``` + +证据关系建议独立表或有界结构化 JSON,并在读取时重新验证对象归属。 + +## 18. 安全与隐私 + +1. Supervisor 使用独立可信系统指令,所有观察输入视为不可信数据。 +2. 默认不给 Supervisor 任何工具。 +3. 即使后续提供只读证据工具,也只能读取绑定对象和明确范围。 +4. Supervisor 不接收 Runtime 授权回调,不能请求工具批准。 +5. 普通会话监督失败不影响主回答;自动化配置的强制监督失败进入明确关注状态。 +6. 评论和通知不包含完整私人消息,证据点击后才在原对象中查看。 +7. Renderer 传入的 Evidence ID 必须由 Main 重新验证归属。 +8. 删除会话时按产品数据保留策略删除或匿名化监督记录。 +9. 用户关闭监督后停止新分析,但保留历史,除非用户明确删除。 + +## 19. 性能与预算 + +- Supervisor 使用独立后台并发池,默认全局并发 1。 +- 前台回复完成后异步运行,不延迟主回答呈现。 +- 同一会话同时只运行一次监督分析,新事件合并为下一次分析。 +- 普通会话每 30 秒最多自动分析一次。 +- 自动化按步骤或关键事件节流。 +- 达到 Supervisor 预算时显示“监督已暂停”,不继续产生费用。 + +## 20. 实施顺序 + +1. 定义监督会话、记录、证据和解决状态。 +2. 上线普通会话手动检查和右侧评论流。 +3. 增加每次回复后异步监督、节流和预算。 +4. 接入任务和自动化的确定性观察。 +5. 增加目标、证据和无进展模型检查。 +6. 接入实验协议一致性监督。 +7. 建立误报和有用性评估,不自动改 Prompt。 + +## 21. 验收标准 + +- [ ] 监督默认关闭,用户可对单个会话显式启用。 +- [ ] Supervisor 只读取当前对象的有界可见事件。 +- [ ] 隐藏推理、密钥和未授权内容不进入监督输入。 +- [ ] 每条中高严重度意见都有可点击证据。 +- [ ] 无证据推测不会显示为高严重度事实。 +- [ ] 模型监督不能自动暂停、终止、批准工具或替用户发言。 +- [ ] 确定性门禁不依赖模型判断即可阻止越权和超预算行为。 +- [ ] 主会话回答不等待后台 Supervisor 完成。 +- [ ] 用户可采纳、忽略、标记误报和解决意见。 +- [ ] 监督评论默认不进入长期记忆。 +- [ ] 自动化强制监督不可用时明确请求关注,不假装检查通过。 +- [ ] Supervisor 预算耗尽后停止新调用并显示状态。 diff --git a/docs/features/parallel-experiments-prd.md b/docs/features/parallel-experiments-prd.md new file mode 100644 index 0000000..922f8ef --- /dev/null +++ b/docs/features/parallel-experiments-prd.md @@ -0,0 +1,388 @@ +# 并行实验工作台 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-08-13 | +| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md)、[自动任务与目标 PRD](./automation-goals-and-scheduling-prd.md) | + +## 1. 背景 + +GoodBuddy 已能把一个请求并行委派给最多三个只读专家,再综合结果。这适合“一次请求, +多种专业视角”,但不等同于实验:当前没有结构化变量、重复运行、统一指标、结果晋升和 +Run 级记忆隔离。 + +本功能借鉴 MesaLogo ParallelLab 中变量隔离、批量 Run、失败结算、指标比较和运行证据 +的思想,但不引入其 Action Space、服务端队列或重型仿真平台。 + +## 2. 产品定义 + +并行实验是在冻结的研究问题和执行协议下,生成多个相互隔离的候选 Run,以相同评估标准 +比较结果,并将结论追溯到运行证据。 + +```text +Experiment + ├─ Question / Hypothesis + ├─ Protocol + ├─ Variables and Variants + ├─ Objectives and Evaluators + ├─ Budget and Stop Conditions + └─ ExperimentRun × N + ├─ Isolated Conversation + ├─ Isolated Run Memory + ├─ Tasks and Artifacts + ├─ Metrics + └─ Evidence +``` + +## 3. 已确认的产品决策 + +1. 实验 Run 复用现有 Task、Runtime、Artifact 和审批机制。 +2. 每个 Run 有独立变量、会话、运行记忆、任务和成果。 +3. 默认实验是只读 Ask;写工作区的实验后续使用每 Run 独立沙箱。 +4. 多个 Run 不能并发修改同一个用户工作区。 +5. 失败、取消、预算耗尽或结果不完整的 Run 不参与最佳结果选择。 +6. 没有成功 Run 时实验为失败或无结论,不能报告成功。 +7. 模型生成的实验协议必须可审查、编辑和版本化。 +8. 评估优先使用确定性指标;模型 Rubric 显示评估器版本和不确定性。 +9. “最佳”只针对声明的目标和约束,不代表普遍最好。 +10. 最佳结果只能创建候选,不能直接覆盖计划、记忆或工作区。 + +## 4. 目标 + +- 把问题转为可审查的实验问题、变量、候选和指标。 +- 比较不同提示、模型、专家组合、参数或方案。 +- 监控每个 Run 的状态、成本、证据和失败原因。 +- 查看结果表、差异、稳定性和评估依据。 +- 从候选创建普通任务、计划草稿或记忆候选。 +- 为持续学习提供回放和非退化评估基础。 + +## 5. 非目标 + +- 第一阶段不模拟数千 Agent 或社会群体涌现。 +- 不实现任意连续参数的自动贝叶斯优化。 +- 不在样本不足时宣称统计显著性。 +- 不把模型的自报置信度直接作为跨模型比较指标。 +- 不允许实验自行增加样本数、预算或能力范围。 +- 不允许自动部署结果或修改安全策略。 +- 不把专家团队的一次回答自动包装成科学实验。 + +## 6. 实验类型 + +| 类型 | 变量示例 | 用途 | +| --- | --- | --- | +| Prompt 对比 | 系统说明、输出格式、示例 | 比较自动化协议 | +| 模型对比 | 已配置文本模型 | 质量、速度和 Token 权衡 | +| 专家组合 | 专家集合、综合策略 | 多视角研究 | +| 参数扫描 | 检索模式、Top K、轮数 | 寻找有限参数组合 | +| 方案候选 | 多个用户或模型方案 | 按统一 Rubric 比较 | +| 回放评估 | 历史脱敏案例集合 | 验证学习候选是否退化 | + +后续多轮情景模拟需要单独定义角色、环境和状态变量。 + +## 7. 创建流程 + +### 7.1 研究问题 + +用户填写: + +- 实验名称。 +- 问题和可选假设。 +- 探索、比较、优化或回放验证类型。 +- 项目范围。 +- 期望输出。 +- 禁止行为。 + +### 7.2 协议 + +`ExperimentProtocol` 包含: + +- 基准输入或案例集。 +- 固定提示和步骤。 +- 变量与候选。 +- Runtime、模型和专家。 +- 工具、知识库和记忆范围。 +- 工作模式。 +- 每 Run 预算。 +- 指标、评估器和停止条件。 +- 重复次数。 + +模型生成协议草稿时必须标明用户字段、模型建议、确定性指标和模型判断指标。 + +### 7.3 变量 + +```ts +type ExperimentVariable = + | { name: string; type: 'enum'; values: JsonValue[] } + | { + name: string + type: 'range' + start: number + end: number + step: number + } + | { name: string; type: 'boolean' } + | { name: string; type: 'prompt_variant'; values: string[] } + | { + name: string + type: 'model_profile' + profileIds: string[] + } + | { + name: string + type: 'expert_set' + expertIdSets: string[][] + } +``` + +第一阶段只支持有限、确定生成的组合。保存前展示组合数、重复后 Run 总数、最大模型调用、 +Token 和耗时范围,以及最大并发。超过上限时要求缩小变量,不静默抽样。 + +### 7.4 基准与候选 + +- 至少一个 Variant。 +- 对比实验建议设置 Baseline。 +- Baseline 与 Candidate 使用相同案例和评估器。 +- 评估器不能读取 Variant 标签和模型名称作为质量信号。 +- 模型评分时随机化候选顺序并保存实际顺序。 + +## 8. Run 隔离 + +### 8.1 数据隔离 + +每个 Run 独立拥有: + +- `experimentRunId` 和运行会话。 +- 变量快照和临时上下文。 +- Run 记忆分区。 +- 任务、子任务和成果。 +- 指标、证据和 Runtime 会话标识。 + +禁止: + +- Run A 读取 Run B 的消息、临时记忆或中间成果。 +- 多个 Run 共享可变变量对象。 +- Run 候选记忆在实验结算前进入其他 Run。 +- 通过全局列表误取其他项目或实验数据。 + +### 8.2 工作区隔离 + +阶段 1 只支持 Ask 和只读工具。阶段 2 的 Execute Run 使用独立临时沙箱或版本化工作树, +结果以 Patch 或成果展示,用户选择候选后再进入单独应用流程。 + +### 8.3 记忆隔离 + +Run 只读取冻结的 Global、Project、Automation 记忆快照和自己的 Run 分区, +不读取其他 Run 或实验期间新产生的候选记忆。 + +## 9. 调度与预算 + +- 默认最大并发 3,与现有子专家调度能力一致。 +- 还需遵守全局后台并发和模型连接并发。 +- 每个 Variant 使用相同的单 Run 预算。 +- 不因候选暂时领先而静默给它更多预算。 +- 提前停止必须来自预先声明的规则。 +- UI 显示运行、排队、成功、失败和取消数量。 + +停止条件: + +```ts +type ExperimentStopCondition = + | { type: 'all_runs_terminal' } + | { type: 'successful_run_count'; count: number } + | { + type: 'metric_threshold' + metric: string + operator: string + value: number + } + | { type: 'budget' } + | { type: 'deadline'; at: string } + | { type: 'manual' } +``` + +触发停止后不启动新 Run;是否取消正在运行的 Run 必须在条件中明确。保存停止原因, +未运行 Variant 不参与最终比较。 + +## 10. 评估与指标 + +### 10.1 指标类型 + +| 类型 | 示例 | +| --- | --- | +| 确定性结果 | Schema 有效、测试通过、文件存在、检查项完成 | +| 运行指标 | 耗时、模型调用、Token、工具调用、成果大小 | +| 检索指标 | 召回、引用覆盖、降级状态 | +| 人工评分 | 正确性、可用性、偏好 | +| 模型 Rubric | 结构、完整性、表达、风险 | + +### 10.2 模型 Rubric + +必须保存 Rubric 版本、评估模型、输入证据摘要、候选展示顺序、分项得分、结构化理由和 +格式修复。它不能覆盖确定性失败,也不能在缺少证据时编造事实正确性判断。 + +### 10.3 多目标 + +```ts +type ExperimentObjective = { + metric: string + direction: 'maximize' | 'minimize' | 'target' + weight?: number + target?: number + hardConstraint?: boolean +} +``` + +结算先排除非成功和违反硬约束的 Run,再计算其余指标。存在明显权衡时展示 Pareto 候选, +不强行选唯一最佳。 + +## 11. 结算规则 + +Run 成功要求: + +- Runtime 正常结束。 +- 必填成果存在。 +- 必填评估器成功。 +- 未违反硬约束。 +- 没有结果未知的副作用。 + +Experiment 结算: + +| 情况 | 状态 | +| --- | --- | +| 至少一个成功 Run,所需 Run 已结算 | `completed` | +| 所有 Run 失败或无有效结果 | `failed` | +| 提前停止且已有可比较结果 | `stopped_with_results` | +| 提前停止且无可比较结果 | `cancelled` | +| 指标冲突或证据不足 | `inconclusive` | + +最佳结果展示 Variant、参数、成功和失败数量、重复运行原始值与聚合、目标分项、硬约束、 +证据和限制。只有一个成功 Run 时使用“当前最高分候选”,不使用“稳定最佳”。 + +## 12. 重复与复现 + +- 每个 Variant 默认重复 1 次,波动敏感实验建议至少 3 次。 +- 重复 Run 使用相同变量和独立运行会话。 +- Runtime 支持种子时保存种子,否则明确标注不可完全复现。 +- 聚合展示原始值、中位数或均值,并说明计算方式。 +- 样本不足时不展示统计显著性结论。 + +## 13. 会话监督接入 + +Supervisor 可以检查偏离协议、遗漏必填输出、证据不足和候选间协议不一致; +确定性预算或权限违规可以暂停 Run,模型判断默认只警告或请求人工复核。 + +Supervisor 不能: + +- 根据其他候选结果提示当前 Run。 +- 临时修改某个候选协议。 +- 自动提高预算或批准工具。 + +## 14. 信息架构 + +实验工作台页签: + +1. **设计**:问题、协议、变量、指标和预算。 +2. **运行**:总体进度、Run 表和状态。 +3. **比较**:指标表、图表、差异和 Pareto 候选。 +4. **证据**:按结论、指标和 Run 查看证据。 +5. **结论**:总结、限制和后续操作。 + +Run 详情展示参数、协议版本、时间线、消息、任务、成果、监督记录、指标、评估理由、 +上下文和记忆快照、Token、耗时与错误。 + +## 15. 后续操作 + +允许: + +- 用候选参数创建普通任务。 +- 创建自动化计划草稿。 +- 保存实验模板。 +- 创建记忆候选。 +- 追加确认 Run。 +- 导出脱敏结果摘要。 + +不得自动启用新计划、覆盖现有计划、确认长期记忆、应用工作区 Patch 或扩大权限。 + +## 16. 数据模型建议 + +```ts +type Experiment = { + id: string + projectId?: string + name: string + question: string + status: + | 'draft' + | 'queued' + | 'running' + | 'paused' + | 'completed' + | 'failed' + | 'stopped_with_results' + | 'inconclusive' + | 'cancelled' + protocolVersion: number + totalRuns: number + successfulRuns: number + failedRuns: number +} + +type ExperimentRun = { + id: string + experimentId: string + variantId: string + repetition: number + automationRunId: string + variables: Record + status: string + goalStatus: 'met' | 'not_met' | 'inconclusive' +} +``` + +建议表: + +- `experiments` +- `experiment_protocol_versions` +- `experiment_variants` +- `experiment_runs` +- `experiment_run_metrics` +- `experiment_evidence` +- `experiment_conclusions` + +## 17. 安全与隐私 + +1. 协议、案例、输出和评估输入都视为不可信数据。 +2. Renderer 不能指定其他项目的 Run 或记忆分区。 +3. 每个 Run 使用唯一 Runtime conversation ID,并在结束后释放。 +4. 实验默认不能写用户工作区。 +5. 模型对比不能传递其他供应商的凭据或隐藏配置。 +6. 导出默认不包含完整私人案例、提示、消息或文件内容。 +7. 取消实验传播到排队和运行任务,但不伪装撤销已有副作用。 +8. 实验删除不能误删已由用户独立保存的成果或计划候选。 + +## 18. 实施顺序 + +1. 建立 Experiment、Variant、Run 聚合实体和只读 Ask Run。 +2. 实现有限组合、预算估算、并发调度和运行监控。 +3. 增加确定性指标、失败结算和结果比较。 +4. 增加模型 Rubric、人工评分和证据工作台。 +5. 增加重复运行和回放评估。 +6. 最后评估独立工作树中的 Execute 实验。 + +## 19. 验收标准 + +- [ ] 保存前显示变量组合、重复后 Run 总数和最大预算。 +- [ ] 每个 Run 的会话、变量、记忆、任务和成果相互隔离。 +- [ ] 默认实验无法写用户工作区。 +- [ ] 最大并发和全局后台预算同时生效。 +- [ ] 各 Variant 使用相同单 Run 预算。 +- [ ] 失败、取消、预算耗尽和不完整 Run 不参与最佳选择。 +- [ ] 全部 Run 失败时实验不报告成功或最佳结果。 +- [ ] 模型 Rubric 显示版本、模型、分项和证据。 +- [ ] 多目标冲突时可以展示多个 Pareto 候选。 +- [ ] 用户可从候选创建草稿,但不会自动部署或确认记忆。 +- [ ] 结论能追溯到具体 Run、指标、成果和证据。 diff --git a/docs/features/partitioned-memory-prd.md b/docs/features/partitioned-memory-prd.md new file mode 100644 index 0000000..e14dbd5 --- /dev/null +++ b/docs/features/partitioned-memory-prd.md @@ -0,0 +1,482 @@ +# 分区记忆 PRD + +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 状态 | 设计中 | +| 版本 | 0.1 | +| 日期 | 2026-08-13 | +| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md) | + +## 1. 背景 + +GoodBuddy 当前记忆已经支持: + +- `global`、`project`、`conversation` 三种作用域。 +- `preference`、`fact`、`summary`、`procedure` 四种类型。 +- `proposed`、`confirmed`、`rejected` 三种状态。 +- 智能心跳提出 Global 或 Project 记忆候选,由用户确认。 + +但当前能力仍不足以支撑自动化和并行实验: + +1. 交互请求会把已加载列表中的最多 20 条已确认记忆直接拼入提示,缺少查询相关度和明确的 + 会话级过滤契约。 +2. 数据库有会话作用域,但心跳只提出 Global 和 Project 记忆。 +3. 缺少 Automation、Experiment 和 Run 分区。 +4. 来源字段存在于表结构,但普通创建和心跳候选尚未完整保存来源关系。 +5. 缺少事实的有效时间、冲突、替代、访问记录和衰减。 +6. 实验 Run 若共享可变记忆,会造成候选互相污染。 + +本设计先完成分区、来源、检索和生命周期,再评估时间知识图谱。 + +## 2. 核心产品判断 + +### 2.1 分区是权限和隔离边界 + +分区不是搜索标签。每次读取先根据运行快照确定允许分区,再在这些分区中检索。 +模型不能请求任意分区 ID,Renderer 也不能把任意 ID 作为可信范围。 + +### 2.2 作用域和记忆种类是两个维度 + +- 作用域回答“谁可以读取”。 +- 类型回答“这是什么信息”。 + +不能用 `summary` 表示会话范围,也不能用 `project` 表示事实类型。 + +### 2.3 记忆和知识库分离 + +| 记忆 | 知识库 | +| --- | --- | +| 用户偏好、项目约定、过程经验、会话摘要 | 文档、网页、文件和外部资料 | +| 小规模、动态、可确认和可遗忘 | 大规模、按来源同步和引用 | +| 强调作用域、来源、时态和行为影响 | 强调检索、分块和证据引用 | + +不能把整个文档或长工具输出保存为记忆。 + +### 2.4 第一阶段不需要图数据库 + +SQLite 显式字段、FTS、来源关系和可选本地 Embedding 足以支持首期。时间图谱只有在以下 +需求经过验证后再建设: + +- 实体关系的多跳查询。 +- 事实有效期和关系演变。 +- 同一实体跨大量会话的别名消歧。 +- 可解释的关系证据链。 + +## 3. 目标 + +- 为会话、自动化和并行 Run 提供严格隔离。 +- 每条记忆显示范围、类型、状态、来源、时间和敏感度。 +- 在允许分区内按相关性、重要性、新鲜度和预算检索。 +- 保留冲突事实和时态,不静默覆盖。 +- 让候选记忆经过确认或评估后再晋升。 +- 支持编辑、移动、合并、拒绝、归档、删除和要求忘记。 +- 记录哪些 Run 实际读取了哪些记忆。 + +## 4. 非目标 + +- 不保存完整聊天、文档、工具日志或隐藏推理作为记忆。 +- 不自动确认敏感个人信息。 +- 不默认跨项目共享 Project、Conversation 或 Run 记忆。 +- 不允许模型自行创建新分区或跨分区移动记忆。 +- 不承诺记忆中的事实永远正确。 +- 第一阶段不建设 Memory Palace 五层空间隐喻。 +- 不把向量相似度作为权限判定。 + +## 5. 分区模型 + +### 5.1 分区类型 + +```ts +type MemoryNamespaceKind = + | 'global' + | 'project' + | 'conversation' + | 'automation' + | 'experiment' + | 'run' + | 'agent' +``` + +| 分区 | 内容 | 生命周期 | +| --- | --- | --- | +| Global | 用户长期偏好和跨项目通用约定 | 长期,严格确认 | +| Project | 项目术语、目标、决策和流程 | 随项目 | +| Conversation | 当前会话摘要、局部约定和待澄清信息 | 随会话或短期 | +| Automation | 某计划的稳定协议经验和运行约定 | 随计划 | +| Experiment | 实验设计、结论和限制 | 随实验 | +| Run | 单次运行观察、中间状态和临时经验 | 短期、严格隔离 | +| Agent | 某专家或角色的个性化经验 | 后续,默认关闭 | + +首期实现 Global、Project、Conversation、Automation 和 Run。Experiment 可复用 +Automation 机制后增加;Agent 必须在专家长期身份明确后再开放。 + +### 5.2 分区标识 + +```text +global +project:{projectId} +conversation:{conversationId} +automation:{planId} +experiment:{experimentId} +run:{automationRunId} +agent:{expertId} +``` + +数据库使用 UUID 外键和显式 `kind`,上述字符串只用于日志和展示,不作为未经验证的访问凭据。 + +### 5.3 读取链 + +交互会话推荐: + +```text +Conversation → Project → Global +``` + +自动化 Run: + +```text +Run → Automation → Conversation(可选)→ Project → Global +``` + +实验 Run: + +```text +Run → Experiment frozen snapshot → Project frozen snapshot → Global frozen snapshot +``` + +各层使用独立结果数和字符预算。Run 层不能覆盖权限更高层,只能提供更具体上下文。 + +## 6. 记忆条目 + +```ts +type MemoryItem = { + id: string + namespaceId: string + kind: + | 'preference' + | 'fact' + | 'summary' + | 'procedure' + | 'decision' + | 'constraint' + | 'reflection' + content: string + status: + | 'candidate' + | 'confirmed' + | 'rejected' + | 'superseded' + | 'archived' + confidence: number + salience: number + sensitivity: 'normal' | 'sensitive' | 'restricted' + validFrom?: string + validTo?: string + expiresAt?: string + sourceId: string + supersedesId?: string + createdAt: string + updatedAt: string +} +``` + +兼容映射: + +- 当前 `proposed` 对应 `candidate`。 +- 当前 `confirmed` 和 `rejected` 保留。 +- 当前四种类型保留,并按真实需求增加 `decision`、`constraint` 和 `reflection`。 + +## 7. 来源与证据 + +### 7.1 来源类型 + +```ts +type MemorySource = + | { type: 'user_entry'; createdBy: 'user' } + | { + type: 'message' + conversationId: string + messageId: string + } + | { type: 'task'; taskId: string; eventId?: string } + | { type: 'heartbeat'; heartbeatRunId: string; entryId: string } + | { type: 'supervisor'; supervisorRecordId: string } + | { type: 'automation_run'; automationRunId: string } + | { + type: 'experiment_conclusion' + experimentId: string + conclusionId: string + } + | { type: 'artifact'; artifactId: string } +``` + +### 7.2 来源规则 + +- 每条非用户手动记忆必须有来源。 +- 来源被删除时记忆不一定删除,但显示“来源不可用”并降低可信度。 +- 来源内容不复制进记忆表,只保存有界证据摘要和引用。 +- 用户确认只表示允许后续使用,不表示事实已被外部验证。 +- Supervisor 判断只能生成候选,不能直接生成确认事实。 + +## 8. 候选生成 + +候选来源: + +- 智能心跳。 +- 用户明确“记住这个”。 +- 会话结束总结。 +- 自动化 Run 结束反思。 +- 实验结论。 +- Supervisor 建议后用户采纳。 + +候选生成必须: + +- 限制数量和长度。 +- 检查同分区近似重复。 +- 标记推断和不确定性。 +- 不自动提取密码、密钥、身份号码、健康和财务等敏感信息。 +- 不把指令型工具输出自动当作用户偏好。 +- 不从助手自己的未确认陈述提取事实。 + +## 9. 确认与晋升 + +### 9.1 允许路径 + +```text +Run candidate + → Automation candidate + → Project candidate + → Global candidate +``` + +每次跨层都是显式晋升,不是移动原记录: + +- 保留原候选和来源。 +- 创建目标分区新版本。 +- 保存晋升理由、评估和操作者。 +- 可回滚到晋升前状态。 + +### 9.2 确认规则 + +- Global 默认必须人工确认。 +- Project 默认人工确认,可对特定低敏感模板启用批量确认。 +- Conversation 可以由用户“记住”直接确认。 +- Automation 和 Run 由自动化协议决定,但只在自身范围有效。 +- Experiment 结论必须结算成功且显示证据,才可成为 Project 候选。 + +### 9.3 拒绝 + +拒绝后: + +- 不进入检索。 +- 保存规范化摘要指纹,减少重复建议。 +- 用户可查看和恢复。 +- 不把拒绝内容回填给模型,除非用于“避免重复建议”的有界规则。 + +## 10. 检索 + +### 10.1 两步边界 + +```text +根据可信运行上下文确定允许分区 +→ 在允许分区中检索和排序 +``` + +这两步不能颠倒。先全库相似搜索再过滤会增加泄漏和实现风险。 + +### 10.2 排序 + +建议综合: + +- 文本相关度。 +- 可选向量相关度。 +- Salience。 +- Confidence。 +- 新鲜度和有效时间。 +- 类型匹配。 +- 分区优先级。 +- 最近是否已使用。 + +只有 `confirmed`、当前有效且敏感度允许的记忆进入普通上下文。 + +### 10.3 预算 + +建议默认: + +| 层级 | 最大条数 | 最大字符 | +| --- | --- | --- | +| Run | 8 | 4,000 | +| Automation / Experiment | 8 | 4,000 | +| Conversation | 8 | 4,000 | +| Project | 10 | 5,000 | +| Global | 6 | 3,000 | + +总预算还受模型上下文组装器限制。不能每层取满后无界拼接。 + +### 10.4 上下文格式 + +提供给 Runtime 的每条记忆包含: + +- 类型。 +- 范围。 +- 内容。 +- 有效时间。 +- 来源类型和可选引用。 +- 不确定或冲突标记。 + +可信指令明确说明记忆是用户确认的信息或候选证据,不是系统指令。 + +## 11. 冲突与时态 + +### 11.1 冲突 + +新条目与现有条目冲突时: + +- 不静默覆盖。 +- 创建冲突关系。 +- 向用户展示两个内容、来源、时间和范围。 +- 用户可选择保留两者、设定有效期、替代旧条目或拒绝新条目。 + +### 11.2 时态 + +事实和决策支持: + +- `validFrom`:何时开始有效。 +- `validTo`:何时不再有效。 +- `observedAt`:何时被系统观察。 +- `createdAt`:何时写入数据库。 + +例如“项目目标是 8 月发布”变更为“延期到 9 月”时,旧事实保留历史有效期,新事实成为 +当前有效版本。 + +### 11.3 适用范围冲突 + +Project 记忆与 Global 偏好冲突时: + +- 当前 Project 的更具体约定优先。 +- 上下文中标明这是项目级覆盖。 +- 不修改 Global 原记录。 + +## 12. 实验隔离 + +- 实验启动时冻结可读长期记忆快照。 +- 各 Run 拥有独立 Run 分区。 +- Run 期间产生的候选不互相可见。 +- 实验结算后只从成功 Run 和有效证据生成 Experiment 候选。 +- 最佳 Run 的临时经验不会自动晋升。 +- 重跑相同协议可以选择复用原冻结快照或创建新版本,必须明确显示。 + +## 13. 生命周期与衰减 + +### 13.1 访问记录 + +保存有界使用记录: + +- 哪个 Run 检索了该记忆。 +- 是否实际进入模型上下文。 +- 是否被用户或评估器认为有用。 +- 最近使用时间和命中次数。 + +不保存完整请求副本。 + +### 13.2 衰减 + +- Preference、Constraint 和 Procedure 不仅因时间自动失效。 +- Conversation、Run Summary 和 Reflection 可配置过期时间。 +- 长期未命中、低 Salience 的候选可归档。 +- 衰减先影响排序,再进入归档,不直接硬删除。 +- Restricted 记忆可采用更短保留期。 + +### 13.3 删除与忘记 + +- 删除记忆后立即停止检索。 +- “忘记”同时清理派生索引、Embedding 和缓存。 +- 来源消息是否删除由其自身生命周期决定,不能反向静默删除用户会话。 +- 删除 Project 时清理其分区、自动化和 Run 记忆,不影响 Global。 +- 审计只保留不含原内容的删除事件和 ID 摘要。 + +## 14. 敏感信息 + +| 敏感度 | 行为 | +| --- | --- | +| Normal | 按普通确认和检索规则 | +| Sensitive | 必须人工确认,UI 持续标记 | +| Restricted | 默认不允许模型自动生成;仅用户手动创建,读取需要显式启用 | + +禁止自动长期记忆: + +- 密码、密钥、Token、Cookie。 +- 完整身份证件、银行卡和账户凭据。 +- 未经用户明确要求的健康、财务和高度私密信息。 +- 工具输出中的认证数据。 + +## 15. 信息架构 + +记忆中心建议页签: + +1. **记忆**:按范围、类型、状态和敏感度浏览。 +2. **待确认**:候选、冲突和晋升请求。 +3. **分区**:Global、Project、Conversation、Automation、Run 的统计和访问策略。 +4. **使用记录**:哪些 Run 使用了哪些记忆。 +5. **设置**:候选生成、保留期、敏感信息和检索预算。 + +每条记忆展示内容、类型、范围、来源、状态、时间、置信度、重要性和冲突。 + +## 16. 数据模型建议 + +建议表: + +- `memory_namespaces` +- `memory_items` +- `memory_sources` +- `memory_relations` +- `memory_access_events` +- `memory_promotion_events` +- `memory_embeddings`,可选 + +现有 `memory_items` 可渐进迁移: + +1. 增加 Namespace 并回填现有 Scope。 +2. 回填来源为空的旧记录为 `legacy_unknown`。 +3. 增加状态和类型兼容映射。 +4. 上线新检索器后再停止旧的列表拼接方式。 + +## 17. 安全与隐私 + +1. 分区解析只在 Main 进行。 +2. 所有 ID 重新验证对象归属和项目范围。 +3. Renderer 无法指定任意分区进行搜索。 +4. Runtime 只能获得有界记忆文本和来源摘要。 +5. Embedding 只能发送用户已配置允许的记忆,Restricted 默认不发送外部服务。 +6. 记忆内容和来源不出现在普通日志与通知。 +7. 跨分区晋升需要明确操作和审计。 +8. Ask 和 Execute 使用同一只读记忆检索边界。 +9. 记忆不能绕过系统指令、工具审批和工作区权限。 + +## 18. 实施顺序 + +1. 修正当前交互请求的范围过滤,确保只读 Global、当前 Project 和当前 Conversation。 +2. 增加来源记录和“实际进入上下文”的诊断。 +3. 建立 Automation 和 Run Namespace。 +4. 上线有界相关检索,替换简单列表前 20 条拼接。 +5. 增加冲突、时态、替代和归档。 +6. 增加实验冻结快照与 Run 隔离。 +7. 增加可选本地 Embedding 和混合排序。 +8. 只有明确需求后再评估时间知识图谱。 + +## 19. 验收标准 + +- [ ] 普通会话只读取 Global、当前 Project 和当前 Conversation 的允许记忆。 +- [ ] 自动化 Run 只读取运行快照绑定的分区。 +- [ ] 实验 Run 不能读取其他 Run 的消息或记忆。 +- [ ] 每条非手动记忆都有可追溯来源。 +- [ ] 候选和被拒绝记忆不进入普通上下文。 +- [ ] Global 和 Project 晋升需要明确确认或评估。 +- [ ] 冲突事实不被静默覆盖。 +- [ ] 当前有效事实可通过有效时间正确选择。 +- [ ] 上下文组装遵守各层和总字符预算。 +- [ ] UI 能显示某次 Run 实际使用的记忆。 +- [ ] 删除或忘记后,文本、索引和缓存不再可检索。 +- [ ] Restricted 记忆不会自动生成或发送给外部 Embedding 服务。 diff --git a/docs/长期助手功能规划.md b/docs/long-term-assistant-roadmap.md similarity index 98% rename from docs/长期助手功能规划.md rename to docs/long-term-assistant-roadmap.md index de40db0..ecac534 100644 --- a/docs/长期助手功能规划.md +++ b/docs/long-term-assistant-roadmap.md @@ -1,5 +1,15 @@ # GoodBuddy 长期助手功能规划 +## 文档信息 + +| 项目 | 内容 | +| --- | --- | +| 文档类型 | 产品路线图 | +| 状态 | 规划中 | +| 版本 | 0.1 | +| 日期 | 2026-08-12 | +| 适用产品 | GoodBuddy 桌面端 | + ## 1. 文档目标 本文定义 GoodBuddy 从“安全对话助手”演进为“可长期使用的桌面工作助手”所需的产品能力、交互结构、数据模型、权限边界、实施阶段和验收标准。