# 自动任务、目标与调度 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。
- [ ] 重启后不自动重放结果未知的副作用步骤。
- [ ] 后台任务排队时不挤占前台模型请求。